用途:指导在 .NET 8.0+ SDK(MSBuild 17.8+)下编写自定义 MSBuild 任务,示例均使用 SDK 风格项目。
主要能力:实现 ITask 接口(通常继承 Microsoft.Build.Utilities.Task,获得 BuildEngine、HostObject 与 Log 日志辅助方法);继承 ToolTask 包装外部命令行工具,重写 ToolName、GenerateFullPathToTool、GenerateCommandLineCommands、GenerateResponseFileCommands、HandleTaskExecutionErrors 等;实现 IIncrementalTask(需 MSBuild 17.8+、VS 2022 17.8+、.NET 8 SDK)接收引擎预过滤的变更项,配合目标 Inputs/Outputs 使用,FailIfIncrementalBuildIsNotPossible 控制无法增量时回退或报错;用 CodeTaskFactory 编写内联任务(Fragment、Method、Class 三种代码类型,可加 Reference);用 UsingTask 按 AssemblyFile 或 AssemblyName 注册任务,支持条件注册;通过 [Required]、[Output] 属性声明参数,支持 string、bool、int、string[]、ITaskItem、ITaskItem[] 类型及元数据读写。
使用方式:任务参数为公共属性,MSBuild 自动映射 XML 属性;输出参数经 Output 元素传给后续目标;调试需将调试器附加到 MSBuild 进程,可设置 MSBUILDDEBUGONSTART 环境变量(值为 1 时启动调用 Debugger.Launch())。
适用场景:需要自定义构建逻辑、包装 CLI 工具、对大量文件做增量处理或快速编写简单内联逻辑时。
限制:IIncrementalTask 不能用于面向更早 MSBuild 版本的任务;内联任务适合简单自包含逻辑,复杂逻辑或跨项目复用应编译为程序集并通过 NuGet 分发;MSBuild 项目系统编写(targets、props、items、conditions)不属于本技能范围。调试部分资料在 MSBUILDDEBUGONSTART 处截断,其余取值暂未提供。