Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
28 commits
Select commit Hold shift + click to select a range
7e4e244
support binding to AbsolutePath and AbsolutePath[] for task input/out…
baronfel Jan 13, 2026
8a342ee
Allow users to bind to primitive types while still having access to m…
baronfel Jan 13, 2026
bba8cd3
Support FileInfo/DirectoryInfo parameter binding as well
baronfel Jan 13, 2026
0686891
Remove dead #if !TASKHOST guards from TaskParameterTypeVerifier
baronfel Jun 4, 2026
4c1bdf2
Fix task host crash serializing typed task outputs
baronfel Jun 4, 2026
bdf2ef3
Fix TaskItem<T> parse errors surface as InvalidProjectFileException
baronfel Jun 4, 2026
2c481c8
Use mutable TaskItem backing for TaskItem<T>
baronfel Jun 4, 2026
5a4db7e
Use FullPath metadata for path-like T in TaskItem<T>
baronfel Jun 4, 2026
ef3b4ee
Use EqualityComparer<T>.Default in TaskItem<T> equality
baronfel Jun 4, 2026
ce1ff32
Ensure ITaskItem<T>[] arrays are recognized in TaskParameterTypeVerifier
baronfel Jun 5, 2026
90ef8e2
Fix TaskItem<T>[] output type verification
baronfel Jun 5, 2026
54e6df4
Restrict ITaskItem<T> binding to path-like types (AbsolutePath, FileI…
baronfel Jun 5, 2026
11b2648
Potential fix for pull request finding
baronfel Jun 5, 2026
7a77c33
Use existing boolean conversion helpers instead of reimplementing
baronfel Jun 5, 2026
e150dd5
Update docs to align with parsed value types
baronfel Jun 5, 2026
1ce47a9
Consolidate TaskItem<T> helper logic in shared verifier
baronfel Jun 5, 2026
3548eb0
actually escape set value in wrapped ITaskItem
baronfel Jun 5, 2026
316ee70
fix potential nullrefs on uninitialized TaskItem<T> structs.
baronfel Jun 5, 2026
aa28234
Unify task parameter helper logic across hosts
baronfel Jun 5, 2026
9603335
Fix shared task-parameter helpers for TaskHost builds
baronfel Jun 5, 2026
ab16052
Address Rainer and Jan review feedback
baronfel Jun 17, 2026
915167e
Rip out abstracted reflection usage in TaskItem<T> creation
baronfel Jun 17, 2026
865d6aa
Fix TaskItem<T> construction to use generic argument, not closed type
baronfel Jun 17, 2026
5888292
Add TestEnvironment.PublishTestFile for collecting CI artifacts
baronfel Jun 18, 2026
67efb90
Fix BuildCheck CustomCheck E2E tests (NU1605 restore downgrade) (#14137)
OvesN Jun 25, 2026
7ddc75c
Add typed-parameter binding benchmark and cache TaskItem<T> construct…
baronfel Jun 25, 2026
0018057
Address review feedback: nullable pragmas, case-insensitive metadata,…
baronfel Jul 1, 2026
3e37eb8
Merge remote-tracking branch 'origin/main' into pr/13971/typed-params…
baronfel Jul 1, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 18 additions & 2 deletions documentation/wiki/Tasks.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,24 @@ A task is a class implementing [`ITask`](https://github.com/dotnet/msbuild/blob/

- The notable method of this interface is `bool Execute()`. Code in it will get executed when the task is run.
- A Task can have public properties that can be set by the user in the project file.
- These properties can be `string`, `bool`, `ITaskItem` (representation of a file system object), `string[]`, `bool[]`, `ITaskItem[]`
- the properties can have attributes `[Required]` which causes the engine to check that it has a value when the task is run and `[Output]` which exposes the property to be used again in XML
- These properties can be:
- **String types**: `string`, `string[]`
- **Boolean types**: `bool`, `bool[]`
- **Item types**: `ITaskItem` (representation of a file system object with metadata), `ITaskItem[]`
- **Strongly-typed items**: `ITaskItem<T>` where `T` is `AbsolutePath`, `FileInfo`, or `DirectoryInfo` (e.g., `ITaskItem<AbsolutePath>`, `ITaskItem<FileInfo>`), and their array equivalents
Comment thread
baronfel marked this conversation as resolved.
Resolved
- **Path types**: `AbsolutePath`, `AbsolutePath[]`, `FileInfo`, `FileInfo[]`, `DirectoryInfo`, `DirectoryInfo[]`

> The engine also accepts arbitrary value types (such as `int`, `DateTime`, or any custom struct) by converting to/from their string representation, but using them is discouraged. Prefer the documented types above.

Guidance on choosing a type:
- Use `string`/`string[]` only when the value is genuinely free-form text (a message, an identifier, a raw switch). If the value is a path, prefer one of the path types below so the engine roots it consistently and you avoid re-implementing path resolution in the task.
- Use `AbsolutePath` when you need a fully-rooted path but do not need to touch the file system. The engine roots the incoming value against the project directory for you, and `AbsolutePath` is a lightweight struct that just carries the rooted string — pick it over `string` whenever a parameter is conceptually a path.
- Use `FileInfo` when the parameter represents a single file and the task wants the `System.IO.FileInfo` conveniences (`Exists`, `Length`, `Directory`, `LastWriteTime`, etc.) without constructing the `FileInfo` itself. The value is rooted before the `FileInfo` is created, so relative inputs won't accidentally resolve against the process working directory.
- Use `DirectoryInfo` for the directory equivalent of the above (a single directory parameter where the task wants `System.IO.DirectoryInfo` members). As with `FileInfo`, the path is rooted before construction.
- Use `ITaskItem`/`ITaskItem[]` when the task needs item **metadata** (e.g. `Identity`, `RecursiveDir`, or custom metadata) in addition to the item spec.
- Use `ITaskItem<T>` (e.g. `ITaskItem<AbsolutePath>`, `ITaskItem<FileInfo>`, `ITaskItem<DirectoryInfo>`) when you need **both** item metadata **and** the strongly-typed, pre-rooted value — the `Value` property exposes the parsed `T` while the item still carries its metadata. Prefer this over taking a bare `ITaskItem` and re-parsing `ItemSpec` yourself.
- Prefer the scalar path types (`AbsolutePath`/`FileInfo`/`DirectoryInfo`) over `string` even for optional parameters; they make the task's intent explicit and centralize rooting in the engine.
- The properties can have attributes `[Required]` which causes the engine to check that it has a value when the task is run and `[Output]` which exposes the property to be used again in XML

- Tasks have the `Log` property set by the engine to log messages/errors/warnings.

Expand Down
300 changes: 300 additions & 0 deletions src/Build.UnitTests/BackEnd/TaskBuilderTestTask.cs
Original file line number Diff line number Diff line change
Expand Up @@ -236,6 +236,56 @@ public CustomStruct(IConvertible value)
/// </summary>
private ITaskItem[] _itemArrayOutput;

/// <summary>
/// The value for the AbsolutePathOutput.
/// </summary>
private AbsolutePath _absolutePathOutput;

/// <summary>
/// The value for the AbsolutePathArrayOutput.
/// </summary>
private AbsolutePath[] _absolutePathArrayOutput;

/// <summary>
/// The value for the FileInfoOutput.
/// </summary>
private System.IO.FileInfo _fileInfoOutput;

/// <summary>
/// The value for the FileInfoArrayOutput.
/// </summary>
private System.IO.FileInfo[] _fileInfoArrayOutput;

/// <summary>
/// The value for the DirectoryInfoOutput.
/// </summary>
private System.IO.DirectoryInfo _directoryInfoOutput;

/// <summary>
/// The value for the DirectoryInfoArrayOutput.
/// </summary>
private System.IO.DirectoryInfo[] _directoryInfoArrayOutput;

/// <summary>
/// The value for the TaskItemFileInfoOutput.
/// </summary>
private ITaskItem<System.IO.FileInfo> _taskItemFileInfoOutput;

/// <summary>
/// The value for the TaskItemFileInfoArrayOutput.
/// </summary>
private ITaskItem<System.IO.FileInfo>[] _taskItemFileInfoArrayOutput;

/// <summary>
/// The value for the TaskItemDirectoryInfoOutput.
/// </summary>
private ITaskItem<System.IO.DirectoryInfo> _taskItemDirectoryInfoOutput;

/// <summary>
/// The value for the TaskItemDirectoryInfoArrayOutput.
/// </summary>
private ITaskItem<System.IO.DirectoryInfo>[] _taskItemDirectoryInfoArrayOutput;

/// <summary>
/// Property determining if Execute() should throw or not.
/// </summary>
Expand Down Expand Up @@ -629,6 +679,126 @@ public ITaskItem[] ItemArrayParam
}
}

/// <summary>
/// An AbsolutePath parameter.
/// </summary>
public AbsolutePath AbsolutePathParam
{
set
{
_absolutePathOutput = value;
_testTaskHost?.ParameterSet("AbsolutePathParam", value);
}
}

/// <summary>
/// An AbsolutePath array parameter.
/// </summary>
public AbsolutePath[] AbsolutePathArrayParam
{
set
{
_absolutePathArrayOutput = value;
_testTaskHost?.ParameterSet("AbsolutePathArrayParam", value);
}
}

/// <summary>
/// A FileInfo parameter.
/// </summary>
public System.IO.FileInfo FileInfoParam
{
set
{
_fileInfoOutput = value;
_testTaskHost?.ParameterSet("FileInfoParam", value);
}
}

/// <summary>
/// A FileInfo array parameter.
/// </summary>
public System.IO.FileInfo[] FileInfoArrayParam
{
set
{
_fileInfoArrayOutput = value;
_testTaskHost?.ParameterSet("FileInfoArrayParam", value);
}
}

/// <summary>
/// A DirectoryInfo parameter.
/// </summary>
public System.IO.DirectoryInfo DirectoryInfoParam
{
set
{
_directoryInfoOutput = value;
_testTaskHost?.ParameterSet("DirectoryInfoParam", value);
}
}

/// <summary>
/// A DirectoryInfo array parameter.
/// </summary>
public System.IO.DirectoryInfo[] DirectoryInfoArrayParam
{
set
{
_directoryInfoArrayOutput = value;
_testTaskHost?.ParameterSet("DirectoryInfoArrayParam", value);
}
}

/// <summary>
/// An ITaskItem&lt;FileInfo&gt; parameter.
/// </summary>
public ITaskItem<System.IO.FileInfo> TaskItemFileInfoParam
{
set
{
_taskItemFileInfoOutput = value;
_testTaskHost?.ParameterSet("TaskItemFileInfoParam", value);
}
}

/// <summary>
/// An ITaskItem&lt;FileInfo&gt; array parameter.
/// </summary>
public ITaskItem<System.IO.FileInfo>[] TaskItemFileInfoArrayParam
{
set
{
_taskItemFileInfoArrayOutput = value;
_testTaskHost?.ParameterSet("TaskItemFileInfoArrayParam", value);
}
}

/// <summary>
/// An ITaskItem&lt;DirectoryInfo&gt; parameter.
/// </summary>
public ITaskItem<System.IO.DirectoryInfo> TaskItemDirectoryInfoParam
{
set
{
_taskItemDirectoryInfoOutput = value;
_testTaskHost?.ParameterSet("TaskItemDirectoryInfoParam", value);
}
}

/// <summary>
/// An ITaskItem&lt;DirectoryInfo&gt; array parameter.
/// </summary>
public ITaskItem<System.IO.DirectoryInfo>[] TaskItemDirectoryInfoArrayParam
{
set
{
_taskItemDirectoryInfoArrayOutput = value;
_testTaskHost?.ParameterSet("TaskItemDirectoryInfoArrayParam", value);
}
}

/// <summary>
/// The Execute return value parameter.
/// </summary>
Expand Down Expand Up @@ -1175,6 +1345,136 @@ public ITaskItem[] ItemArrayNullOutput
}
}

/// <summary>
/// An AbsolutePath output.
/// </summary>
[Output]
public AbsolutePath AbsolutePathOutput
{
get
{
_testTaskHost?.OutputRead("AbsolutePathOutput", _absolutePathOutput);
return _absolutePathOutput;
}
}

/// <summary>
/// An AbsolutePath array output.
/// </summary>
[Output]
public AbsolutePath[] AbsolutePathArrayOutput
{
get
{
_testTaskHost?.OutputRead("AbsolutePathArrayOutput", _absolutePathArrayOutput);
return _absolutePathArrayOutput;
}
}

/// <summary>
/// A FileInfo output.
/// </summary>
[Output]
public System.IO.FileInfo FileInfoOutput
{
get
{
_testTaskHost?.OutputRead("FileInfoOutput", _fileInfoOutput);
return _fileInfoOutput;
}
}

/// <summary>
/// A FileInfo array output.
/// </summary>
[Output]
public System.IO.FileInfo[] FileInfoArrayOutput
{
get
{
_testTaskHost?.OutputRead("FileInfoArrayOutput", _fileInfoArrayOutput);
return _fileInfoArrayOutput;
}
}

/// <summary>
/// A DirectoryInfo output.
/// </summary>
[Output]
public System.IO.DirectoryInfo DirectoryInfoOutput
{
get
{
_testTaskHost?.OutputRead("DirectoryInfoOutput", _directoryInfoOutput);
return _directoryInfoOutput;
}
}

/// <summary>
/// A DirectoryInfo array output.
/// </summary>
[Output]
public System.IO.DirectoryInfo[] DirectoryInfoArrayOutput
{
get
{
_testTaskHost?.OutputRead("DirectoryInfoArrayOutput", _directoryInfoArrayOutput);
return _directoryInfoArrayOutput;
}
}

/// <summary>
/// An ITaskItem&lt;FileInfo&gt; output.
/// </summary>
[Output]
public ITaskItem<System.IO.FileInfo> TaskItemFileInfoOutput
{
get
{
_testTaskHost?.OutputRead("TaskItemFileInfoOutput", _taskItemFileInfoOutput);
return _taskItemFileInfoOutput;
}
}

/// <summary>
/// An ITaskItem&lt;FileInfo&gt; array output.
/// </summary>
[Output]
public ITaskItem<System.IO.FileInfo>[] TaskItemFileInfoArrayOutput
{
get
{
_testTaskHost?.OutputRead("TaskItemFileInfoArrayOutput", _taskItemFileInfoArrayOutput);
return _taskItemFileInfoArrayOutput;
}
}

/// <summary>
/// An ITaskItem&lt;DirectoryInfo&gt; output.
/// </summary>
[Output]
public ITaskItem<System.IO.DirectoryInfo> TaskItemDirectoryInfoOutput
{
get
{
_testTaskHost?.OutputRead("TaskItemDirectoryInfoOutput", _taskItemDirectoryInfoOutput);
return _taskItemDirectoryInfoOutput;
}
}

/// <summary>
/// An ITaskItem&lt;DirectoryInfo&gt; array output.
/// </summary>
[Output]
public ITaskItem<System.IO.DirectoryInfo>[] TaskItemDirectoryInfoArrayOutput
{
get
{
_testTaskHost?.OutputRead("TaskItemDirectoryInfoArrayOutput", _taskItemDirectoryInfoArrayOutput);
return _taskItemDirectoryInfoArrayOutput;
}
}

[Output]
public TargetBuiltReason EnumOutput => TargetBuiltReason.BeforeTargets;

Expand Down
Loading
Loading