Search code examples
c#msbuildmsbuild-task

Reading msbuild syntax

I've run across msbuild syntax that I don't understand. The following snippet is from another question about making a custom msbuild task 

<GenerateDesignerDC
  InputFiles="@(dbml)"
  OutputFiles="@(dbml->'$(IntermediateOutputPath)%(FileName).designer.cs')">
    ...

What does @(dbml->'$(IntermediateOutputPath)%(FileName).designer.cs') mean? The @ sign usually references the files in an ItemGroup; what does the -> arrow inside an @(...) mean?

What is this little language (with the @s, $s, %s, ->, etc.) used for substitutions into the attributes of build tasks called?

Solution

  • This specific syntax is called a transform.

    A transform is a one-to-one conversion of one item list to another. In addition to enabling a project to convert item lists, a transform enables a target to identify a direct mapping between its inputs and outputs.

    The syntax isn't explicitly documented. The part before the -> is an item list like that which would normally be referenced by @. In the example @(dbml->...) it is transforming the dbml item list. The part after the -> is an expression for the new file name. It can refer to any item metadata with a % symbol. In the example it's constructing a string with the $(IntermediateOutputPath) property and the %(Filename) well-known item metadata.

    The well-known item metadata should be available for any item and includes most notably the path to the item

    MetaData        Example     
%(FullPath)     C:\MyProject\Source\Program.cs
%(RootDir)      C:\
%(Directory)       MyProject\Source\
%(Filename)                         Program
%(Extension)                               .cs