Calling item functions on the result of a transform

[ltrzesniewski]

Apparently, the following works:

<ItemGroup>
  <Bar Include="@(Foo->'%(Bar).Baz'->ClearMetadata())" />
</ItemGroup>

I can call an item function (ClearMetadata()) on the result of a transform expression which looks like a string, and it works:

But string functions also work:

<ItemGroup>
  <Bar Include="@(Foo->'%(Bar).Baz'->Replace('Baz', 'FooBar'))" />
</ItemGroup>

I'd like to know if calling an item function like this is really supported, or if it just works by coincidence? The syntax looks unintuitive.

The transforms documentation doesn't mention the type of the transform result, and a quick glance on the .NET SDK revealed only one place where an item function is used that way. I didn't expect this to work, since the transform looks like it produces a string, not an item.

Also, I didn't really expect item metadata to be preserved after a transform (since I thought the transform produces a string in the first place), so I suppose that clarifying this in the docs would be nice.

[KalleOlaviNiemitalo]

It doesn't look like a coincidence to me, but not really documented either, so I'm not sure it will work in future versions.

ExpressionShredder.GetReferencedItemExpressions parses the chaining syntax @(Foo->'%(Bar).Baz'->Replace('Baz', 'FooBar')) and creates an ItemExpressionCapture instance for each function call, then a higher-level ItemExpressionCapture instance whose Captures property lists all of them. Expander<P, I>.ItemExpander.ExpandExpressionCapture<S> calls the functions.

msbuild/src/Build/Evaluation/ExpressionShredder.cs

Lines 172 to 173 in 9802d43

	// If there's an '->' eat it and the subsequent quoted expression or transform function
	while (Sink(expression, ref i, end, '-', '>') && transformOrFunctionFound)

msbuild/src/Build/Evaluation/ExpressionShredder.cs

Line 193 in 9802d43

ItemExpressionCapture functionCapture = SinkItemFunctionExpression(expression, startTransform, ref i, end);

msbuild/src/Build/Evaluation/ExpressionShredder.cs

Lines 260 to 263 in 9802d43

	// Create an expression capture that encompases the entire expression between the @( and the )
	// with the item name and any separator contained within it
	// and each transform expression contained within it (i.e. each ->XYZ)
	ItemExpressionCapture expressionCapture = new ItemExpressionCapture(startPoint, endPoint - startPoint, expression.Substring(startPoint, endPoint - startPoint), itemName, separator, separatorStart, transformExpressions);

msbuild/src/Build/Evaluation/Expander.cs

Lines 1877 to 1880 in 9802d43

	Stack<TransformFunction<S>> transformFunctionStack = PrepareTransformStackFromMatch<S>(elementLocation, expressionCapture);
	// iterate over the tranform chain, creating the final items from its results
	foreach (Pair<string, S> itemTuple in Transform<S>(expander, includeNullEntries, transformFunctionStack, IntrinsicItemFunctions<S>.GetItemPairEnumerable(itemsOfType)))

Expander<P, I>.ItemExpander.IntrinsicItemFunctions<S>.GetItemTransformFunction searches for the function in IntrinsicItemFunctions<S>, or if not found, uses ExecuteStringFunction, which then searches for the function in System.String.

msbuild/src/Build/Evaluation/Expander.cs

Lines 2076 to 2087 in 9802d43

	MethodInfo itemFunctionInfo = typeof(IntrinsicItemFunctions<S>).GetMethod(functionName, BindingFlags.IgnoreCase | BindingFlags.NonPublic | BindingFlags.Static);
	if (itemFunctionInfo == null)
	{
	functionName = "ExecuteStringFunction";
	itemFunctionInfo = typeof(IntrinsicItemFunctions<S>).GetMethod(functionName, BindingFlags.IgnoreCase | BindingFlags.NonPublic | BindingFlags.Static);
	if (itemFunctionInfo == null)
	{
	ProjectErrorUtilities.ThrowInvalidProject(elementLocation, "UnknownItemFunction", functionName);
	return null;
	}
	}

GetItemTransformFunction also recognizes the @(MyItem->MetadataName()) function-call syntax for reading well-known item metadata such as Filename. I guess that is an undocumented legacy feature; unlike @(MyItem->Metadata("MetadataName")) and @(MyItem->'%(MetadataName)'), it does not support RecursiveDir or custom metadata.

msbuild/src/Build/Evaluation/Expander.cs

Lines 2069 to 2073 in 9802d43

	if (FileUtilities.ItemSpecModifiers.IsDerivableItemSpecModifier(functionName))
	{
	// Create a delegate to the function we're going to call
	transformFunction = new ItemTransformFunction(ItemSpecModifierFunction);
	}

[ltrzesniewski]

Thanks for the analysis.

Expander<P, I>.ItemExpander.IntrinsicItemFunctions<S>.GetItemTransformFunction searches for the function in IntrinsicItemFunctions<S>, or if not found, uses ExecuteStringFunction, which then searches for the function in System.String.

That's good to know, so MSBuild always tries to call item functions first, then falls back to string functions.

It doesn't look like a coincidence to me, but not really documented either, so I'm not sure it will work in future versions.

That's actually why I asked the question: since it's not documented I don't know if I can rely on it in future versions, or if it's just a side effect of the current implementation. Ideally, I'd like someone from MS to comment on it (and maybe document it if it's an intended feature).