Day 2 – MSBuild Properties and Items

Day 2 – MSBuild Properties and Items

Today you will learn how MSBuild handles Properties and Items, how they are evaluated, and how transforms, metadata, and batching work. These concepts are the foundation for real-world custom MSBuild logic.

1. What Are Properties?

Properties are simple key-value pairs. They always store a single string value and are accessed using the syntax $(PropertyName).

<PropertyGroup>
    <Configuration>Debug</Configuration>
    <TargetFramework>net8.0</TargetFramework>
</PropertyGroup>

Examples of built‑in properties:

• $(MSBuildProjectDirectory)
• $(MSBuildProjectName)
• $(Configuration)
• $(Platform)

2. Property Evaluation Rules

• Properties are evaluated top-to-bottom.
• Properties can be redefined later unless marked as global.
• The Condition attribute controls which value applies.

<PropertyGroup>
    <OutputPath Condition=" '$(Configuration)' == 'Debug' ">bin\Debug\</OutputPath>
    <OutputPath Condition=" '$(Configuration)' == 'Release' ">bin\Release\</OutputPath>
</PropertyGroup>

3. What Are Items?

Items represent collections/lists of things such as files, resources, or custom entries. They are accessed using @(ItemName).

<ItemGroup>
    <Image Include="images\*.png" />
    <Document Include="docs\*.pdf" />
</ItemGroup>

4. Item Metadata

Items may have metadata, used during tasks.

<ItemGroup>
    <Image Include="images\logo.png">
        <Quality>High</Quality>
    </Image>
</ItemGroup>

Metadata is accessed using:

%(Image.Quality)

5. Item Transforms

Transforms allow you to create new item lists based on other items. This is very powerful for automation.

Example: change file extension

@(Images->'%(Filename).webp')

Example: prepend folder

@(Documents->'processed\%(Filename)%(Extension)')

6. Batching

Batching means MSBuild will run a task separately for each item or group of items that share the same metadata.

Example:

<Target Name="ShowImages">
    <Message Text="Processing %(Image.Identity) with quality %(Image.Quality)" />
</Target>

If you have 3 images, the task runs 3 times — once per item.

7. Combining Properties and Items

You can mix both in many scenarios.

<Target Name="CopyImages">
    <Copy
        SourceFiles="@(Image)"
        DestinationFolder="$(OutputPath)\images" />
</Target>

8. Hands-On Exercise (10 minutes)

Create a new console project and update your .csproj:

<PropertyGroup>
    <MyFolder>assets</MyFolder>
</PropertyGroup>

<ItemGroup>
    <Asset Include="$(MyFolder)\*.txt" />
</ItemGroup>

<Target Name="ShowAssets">
    <Message Text="Found asset: %(Asset.Identity)" />
</Target>

Run:

dotnet build -t:ShowAssets

9. Summary

• Properties store single values.
• Items store collections.
• Metadata enriches items.
• Transforms reshape item lists.
• Batching runs tasks per item.

10. Day 3 Preview

Tomorrow you will learn:

• Targets in depth
• Target dependencies
• BeforeTargets / AfterTargets
• Using built‑in MSBuild tasks
• Creating your own custom C# task