用途:提供编写自定义 MSBuild Target 的规范模式,帮助诊断和修复自定义目标编写中的反模式,以及跨 SDK 的目标链断裂问题。
主要能力与规则: 三级目标链:每个主要入口点(Build、Rebuild、Clean)委托给一个列出其依赖项的属性,并串联 Before → Core → After。应委托给属性(DependsOnTargets="$(MyTargetDependsOn)"),而非硬编码目标;OnError 放在编排目标内部,确保失败时仍执行清理;空的 Before/After 目标是扩展点,SDK 不应在其中放逻辑。
链扩展:向现有链添加自定义目标时应追加到 DependsOn 属性,如 <CompileDependsOn>$(CompileDependsOn);MyCodeGenTarget</CompileDependsOn>,切勿覆盖整个链导致 SDK 目标丢失。
机制选择:DependsOnTargets 用于目标显式需要其他目标;BeforeTargets/AfterTargets 用于注入自己不拥有的管道。不控制目标文件时优先用 BeforeTargets="CoreCompile"。
Returns 与 Outputs:Returns 指定 MSBuild 任务调用该项目时接收的内容,用于项目间通信;Outputs 用于内部目标的增量性(时间戳检查)。查询目标(GetTargetPath、GetTargetFrameworks)应使用 Returns 而非 Outputs。
命名约定:_前缀为内部目标,CoreXxx 为实现,BeforeXxx/AfterXxx 为空扩展钩子,PrepareXxx 为准备/验证阶段,ResolveXxx 为发现/解析阶段,GetXxx 为轻量查询。
常见陷阱:覆盖 DependsOn 属性会静默丢弃 SDK 目标;在查询目标上使用 Outputs 会导致 MSBuild 因“最新”而跳过并返回过期数据;在 .props 中定义目标会使 SDK 目标的 BeforeTargets 无挂钩点,应移到 .targets;编排目标中忘记 OnError 会导致构建出错时文件跟踪失败,破坏后续增量构建。
限制:资料未提供安装命令、收费、平台或具体使用步骤等信息。