构建工具开发工具CLI【免费下载链接】msbuildThe Microsoft Build Engine (MSBuild) is the build platform for .NET and Visual Studio.项目地址https://gitcode.com/gh_mirrors/ms/msbuild点击查看免费下载本指南以 MSBuild 开源仓库的 Tasks 文档 为主体系统讲解 MSBuild 中任务Task这一核心扩展机制任务是什么、如何通过ITask接口实现、任务属性支持哪些类型、[Required]/[Output]特性如何工作以及TaskRegistry、TaskExecutionHost、TaskFactory三者如何协作完成一次任务执行。读完本文你将掌握编写自定义任务与自定义任务工厂的完整方法论并理解内联代码任务RoslynCodeTaskFactory与程序集任务AssemblyTaskFactory的底层差异。任务Task的本质Target 中的执行单元在 MSBuild 中任务Task是 Target 内的最小执行单元也是 MSBuild 最主要的扩展点。一个项目文件.csproj/.proj/.targets中的Target元素内部可以放置一个或多个任务元素例如Target NameBuild Csc Sources(Compile) OutputAssembly$(OutputPath)App.dll / /Target这里的Csc、Message、Copy等都是任务。从实现角度看一个任务就是一个实现了ITask接口的类接口定义见 src/Framework/ITask.cs。ITask接口非常精简只包含三部分bool Execute()接口中最重要的方法。任务被运行时Execute()中的代码即被调用返回值true表示成功、false表示失败。源码注释还强调如果任务在Execute()中抛出异常引擎会自动视为任务失败见 src/Framework/ITask.cs。IBuildEngine BuildEngine由引擎注入的回调接口任务可以通过它向引擎报告消息、错误、警告或发起子构建IBuildEngine的扩展接口IBuildEngine2~IBuildEngine9见 src/Framework 目录。ITaskHost HostObject宿主 IDE如 Visual Studio与任务关联的宿主对象没有宿主时可以为null。Log 属性任务与引擎沟通的窗口任务类通常还声明一个Log属性由引擎在运行前注入典型实现是TaskLoggingHelper来自Microsoft.Build.Utilities。任务代码通过Log.LogMessage(...)、Log.LogWarning(...)、Log.LogError(...)等方法输出诊断信息这些信息会进入 MSBuild 的日志体系终端、文件日志或二进制日志。using Microsoft.Build.Framework; using Microsoft.Build.Utilities; public class MyTask : Task // Task 基类已实现 ITask 并提供 Log { public override bool Execute() { Log.LogMessage(MessageImportance.High, Hello from MyTask!); return true; } }任务属性的受支持类型从 string 到强类型路径任务类中的公共属性public properties可以由用户在项目文件中赋值引擎在运行任务前通过反射把 XML 中的值写入这些属性。MSBuild 官方推荐的任务属性类型如下这是选择属性类型时最重要的参考依据类型类别具体类型典型用途字符串string、string[]真正自由形式的文本消息、标识符、原始命令行开关布尔bool、bool[]开关类参数条目ITaskItem、ITaskItem[]需要读取条目元数据Identity、RecursiveDir、自定义元数据的场景强类型条目ITaskItemTT为AbsolutePath、FileInfo或DirectoryInfo及其数组形式同时需要条目元数据和强类型、已 root 的值路径AbsolutePath、AbsolutePath[]、FileInfo、FileInfo[]、DirectoryInfo、DirectoryInfo[]表示文件系统路径的参数引擎也接受任意值类型如int、DateTime或自定义 struct通过字符串表示互相转换但官方不鼓励这样做——请优先使用上表中的类型。类型选择指南来自官方文档并对照源码string/string[]仅当值确实是自由形式文本时使用。如果值是路径请改用路径类型让引擎统一处理路径 root 化避免在任务里重复实现路径解析逻辑。AbsolutePath需要完全 root 的路径但无需访问文件系统时使用。引擎会自动把传入值相对项目目录进行 root 化AbsolutePath是一个轻量 struct只是携带 root 后的字符串。在 src/Framework/PathHelpers/AbsolutePath.cs 可以看到它是readonly struct构造时会校验路径必须是 root 路径否则抛出ArgumentException其相等性比较根据操作系统文件系统大小写敏感性决定Linux 区分大小写Windows/macOS 不区分。只要参数概念上是路径就优先于string使用它。FileInfo参数代表单个文件、且任务想要System.IO.FileInfo的便利成员Exists、Length、Directory、LastWriteTime等时使用。值在创建FileInfo之前会被 root 化因此相对输入不会意外地相对进程工作目录解析。DirectoryInfo单个目录参数、任务想要System.IO.DirectoryInfo成员时的对应选择。与FileInfo一样路径在构造前被 root 化。ITaskItem/ITaskItem[]任务除条目 spec 外还需要条目元数据如Identity、RecursiveDir或自定义元数据时使用。ITaskItem接口见 src/Framework/ITaskItem.cs提供ItemSpec、GetMetadata、SetMetadata、CopyMetadataTo、CloneCustomMetadata等成员。ITaskItemT如ITaskItemAbsolutePath、ITaskItemFileInfo、ITaskItemDirectoryInfo同时需要条目元数据和强类型、预 root 的值时使用——Value属性暴露解析后的T条目本身仍携带元数据。优先于拿裸ITaskItem自己重新解析ItemSpec。接口定义见 [src/Framework/ITaskItem1.cs](https://link.gitcode.com/i/5730cdff9aab3e851327dfccac42ba07)其中Value是从条目的ItemSpec 按 MSBuild 标准解析约定解析出来的强类型值。标量路径类型优先即使对可选参数也建议优先用AbsolutePath/FileInfo/DirectoryInfo而非string它们让任务的意图更明确并把 root 化集中到引擎侧。仓库中的佐证任务参数绑定与静态分析上述强类型建议并非空谈仓库中有两处直接证据基准测试src/MSBuild.Benchmarks/TaskParameterBindingBenchmark.cs 中定义了一个ITaskItemAbsolutePath参数TaskItemAbsolutePathParam并在switch绑定逻辑中演示了引擎如何把值转换为ITaskItemAbsolutePath。TaskAnalyzer 静态分析器src/TaskAnalyzer 目录实现了 Roslyn 分析器专门教导任务作者改用强类型参数当发现new AbsolutePath(Item.ItemSpec)或Path.Combine(Item.ItemSpec, sub)这类手写解析时分析器会建议把属性改为ITaskItemAbsolutePath当 root 路径流入System.IO.File.*或FileStream时建议ITaskItemFileInfo流入System.IO.Directory.*时建议ITaskItemDirectoryInfo数组属性则建议ITaskItemT[]方括号在尖括号外侧详见 src/TaskAnalyzer/README.md。[Required] 与 [Output] 特性任务属性上可以附加两个标准特性[Required]声明该属性是必需输入。引擎在任务运行时检查其是否有值未赋值会直接报错。特性定义见 src/Framework/RequiredAttribute.cs它只能应用于属性AttributeTargets.Property不可继承、不可重复。[Output]声明该属性是任务的输出从而可以在项目文件的Output标签中被再次引用例如把任务输出写入属性或条目。按 src/Framework/OutputAttribute.cs 的注释引擎只允许被标记为[Output]的参数在Output标签中输出数据同时所有参数包括[Output]参数都可以作为输入。典型用法示例public class GenerateVersion : Task { [Required] public string VersionPrefix { get; set; } // 必须由项目文件提供 [Output] public string Version { get; set; } // 可在 Output 中继续使用 public override bool Execute() { Version ${VersionPrefix}.0; return true; } }Target NameGenerate GenerateVersion VersionPrefix1.2 Output TaskParameterVersion PropertyNameFinalVersion / /GenerateVersion Message Text$(FinalVersion) / /Target任务执行的三方协作TaskRegistry、TaskExecutionHost 与 TaskFactory任务的执行并不是直接 new 一个类那么简单MSBuild 引擎内部由三个核心组件分工协作文档中的 Internals 部分TaskRegistry维护构建中所有可用任务的清单并负责解析任务。它跟踪项目文件中通过UsingTask声明的任务。其类注释给出了三条硬性规则见 src/Build/Instance/TaskRegistry.cs不允许同时用程序集名称强名或弱名和文件路径指定任务程序集用程序集名称指定时不得带扩展名通常为.dll用程序集文件指定时必须带扩展名。 它内部使用ConcurrentDictionary对精确匹配与模糊匹配的任务记录做缓存避免重复解析。TaskExecutionHost任务的执行宿主。它在TaskRegistry中查找任务调用TaskFactory创建任务实例然后用反射按 XML 中的值设置属性最后调用任务的Execute()并收集输出。它不接触任务声明与 XML 的任何部分职责划分见 src/Build/BackEnd/TaskExecutionHost/TaskExecutionHost.cs。其FindTask方法会返回TaskRequirements标志见同文件L42-L59RequireSTAThread必须在 STA 线程执行和RequireSeparateAppDomain必须在独立 AppDomain 执行这解释了某些任务为何会被调度到特殊执行上下文。其Execute()方法L791-L817在调用TaskInstance.Execute()前检查取消标志若已取消直接返回false并把返回值作为任务成败依据。它还负责取消处理对不可取消的任务每 5 秒发出首次警告、之后每 15 秒重复警告常量CancelFirstWarningWaitInterval、CancelWarningWaitInterval见L71-L76。TaskFactory负责初始化任务并创建任务实例。ITask类负责运行Execute()方法。任务生命周期完整流程原文档给出了任务从编写到执行的生命周期图Mermaid即实现Implement→ 注册Register→ 在 XML 中使用Use→ 初始化Initialize→ 设置输入属性Setup→ 执行ITask.Execute()→ 收集输出Gather outputs。自定义任务从类到 DLL 再到项目文件用户可以实现ITask更常见的是继承Microsoft.Build.Utilities.Task基类并把它编译成.dll然后在项目文件中通过UsingTask注册UsingTask TaskNameMyTaskClass AssemblyFileMyTasks.dll /TaskName必须与任务类的完整命名空间 类名匹配AssemblyFile指向包含该类的程序集文件必须带扩展名见上文 TaskRegistry 规则。这条声明会让引擎使用AssemblyTaskFactory从.dll中加载任务类型并创建实例。如果想在任务中既带输出又能传递条目列表一个完整的自包含示例// MyTasks.dll 中的任务类 using Microsoft.Build.Framework; using Microsoft.Build.Utilities; public class TouchFiles : Task { [Required] public ITaskItem[] Files { get; set; } public override bool Execute() { foreach (ITaskItem file in Files) { Log.LogMessage($Processing {file.GetMetadata(FullPath)}); System.IO.File.AppendAllText(file.ItemSpec, touched\n); } return !Log.HasLoggedErrors; } }Project UsingTask TaskNameTouchFiles AssemblyFile$(MSBuildProjectDirectory)\bin\MyTasks.dll / ItemGroup Files Includea.txt;b.txt / /ItemGroup Target NameGo TouchFiles Files(Files) / /Target /ProjectTask Factories任务的工厂模式任务工厂Task Factory负责创建任务实例。它们实现ITaskFactory或ITaskFactory2接口。ITaskFactory的核心成员见 src/Framework/ITaskFactory.csstring FactoryName工厂名称Type TaskType该工厂将实例化的任务类型bool Initialize(string taskName, IDictionarystring, TaskPropertyInfo parameterGroup, string taskBody, IBuildEngine taskFactoryLoggingHost)初始化工厂针对内联任务块。注意该成员带有[RequiresUnreferencedCode]标注——工厂通过反射创建运行时发现或生成的任务类型与 trimming 不兼容TaskPropertyInfo[] GetTaskParameters()返回所有参数的描述ITask CreateTask(IBuildEngine taskFactoryLoggingHost)创建任务实例失败返回nullvoid CleanupTask(ITask task)清理任务相关上下文/状态例如某些工厂会为单个任务实例创建 AppDomain这里是关闭它的机会。工厂的职责例如从程序集加载任务并初始化它。内置 Task Factories工厂路径说明AssemblyTaskFactorysrc/Build/Instance/TaskFactories/AssemblyTaskFactory.cs从 .NET 程序集构造任务对应UsingTask AssemblyFile.../AssemblyName...。它实现ITaskFactory3内部用TypeLoader.CreateITask()加载继承自ITask/ITask2的类型见该文件L36-L43RoslynCodeTaskFactorysrc/Tasks/RoslynCodeTaskFactory/RoslynCodeTaskFactory.cs内联代码任务UsingTask内直接写 C#/VB 代码构建时用 Roslyn 编译。它同时实现ITaskFactory与IOutOfProcTaskFactory见该文件L27CodeTaskFactory、XamlTaskFactory——旧的、很少使用的工厂RoslynCodeTaskFactory 内联任务RoslynCodeTaskFactory是当前推荐的内联任务方案。其实现细节src/Tasks/RoslynCodeTaskFactory/RoslynCodeTaskFactory.cs显示它默认引入一批命名空间Microsoft.Build.Framework、Microsoft.Build.Utilities、System、System.Collections、System.Collections.Generic、System.IO、System.Linq、System.Text用户无需重复using默认引用Microsoft.Build.Framework、Microsoft.Build.Utilities.Core、mscorlib、netstandard程序集支持CS别名CSharp、C#与VB别名VisualBasic、Visual Basic两种语言使用ConcurrentDictionaryRoslynCodeTaskFactoryTaskInfo, ...缓存已编译程序集保证相同的任务声明不会被重复编译见该文件L86-L89。内联任务示例Project UsingTask TaskNameHelloInline TaskFactoryRoslynCodeTaskFactory AssemblyFile$(MSBuildToolsPath)\Microsoft.Build.Tasks.Core.dll ParameterGroup Name ParameterTypeSystem.String Requiredtrue / /ParameterGroup Task Code TypeFragment Languagecs Log.LogMessage(MessageImportance.High, Hello, Name !); /Code /Task /UsingTask Target NameSayHello HelloInline NameMSBuild / /Target /Project自定义 Task Factories极少用到的扩展点自定义任务工厂是一种很少使用的扩展方式。用户可以实现ITaskFactory来创建自己的任务工厂然后在项目文件中通过Factory属性指定并可在Task子元素中放置工厂初始化所需的内部内容UsingTask TaskNameMyTask AssemblyFileFactory.dll FactoryMyTaskFactory TaskInsides that the MyTaskFactory uses to initialize/Task /UsingTask工厂的Initialize方法会收到taskBody即Task元素内部内容用于初始化CreateTask负责产出任务实例。需要强调的是目前只有 MSBuild 自带的工厂标记了IOutOfProcTaskFactory接口见 src/Framework/IOutOfProcTaskFactory.cs支持跨进程执行该接口是内部接口用于把 MSBuild 自带的工厂与外部自定义工厂区分开外部自定义工厂无法在进程外执行。关于强制内联任务进程外执行的 Trait环境变量MSBUILDFORCEINLINETASKFACTORIESOUTOFPROC会强制内联任务在进程外的 TaskHost 中执行但它与自定义 TaskFactories 不兼容。从源码可以印证这一约束内联任务工厂的进程外执行能力依赖IOutOfProcTaskFactory标记只有 MSBuild 自带工厂实现它而自定义工厂没有该标记同时 src/Build/Instance/TaskFactoryEngineContext.cs 中的ForceOutOfProcessExecution属性正是由该环境变量控制供任务工厂在Initialize()阶段决定是否编译为进程外执行版本IsMultiThreadedBuild属性同理供工厂判断是否按/mt多线程模式编译。什么时候用哪种任务形态决策速查场景推荐方案简单逻辑、想随项目文件分发、不想单独建类库RoslynCodeTaskFactory内联任务逻辑较复杂、需要单元测试、多处复用实现ITask的类库 UsingTask AssemblyFile参数是路径且不需要文件系统 APIAbsolutePath或ITaskItemAbsolutePath当需要元数据参数是单个文件/目录且需要 IO 便利成员FileInfo/DirectoryInfo或ITaskItemFileInfo/ITaskItemDirectoryInfo参数是条目且需要元数据ITaskItem/ITaskItem[]需要全新任务创建语义如从代码生成任务自定义ITaskFactory注意进程外执行限制进一步阅读官方任务的完整实现与示例见 src/Tasks 目录含 297 个.cs源文件与配套.targets/.props任务执行宿主的单元测试src/Build.UnitTests/BackEnd/TaskExecutionHost_Tests.csRoslynCodeTaskFactory 的测试src/Tasks.UnitTests/RoslynCodeTaskFactory_Tests.cs任务参数类型静态分析器帮助迁移到强类型参数src/TaskAnalyzer/README.md任务参数绑定基准src/MSBuild.Benchmarks/TaskParameterBindingBenchmark.cs仓库还提供了可运行的示例任务项目src/Samples/PortableTask、src/Samples/TaskWithDependency、src/Samples/TaskUsageLogger另外微软官方文档中关于MSBuild 任务任务引用任务编写创建自定义任务教程等内容原文档的 Microsoft Learn Resources 一节可作延伸学习本仓库文档 Tasks 与官方文档互为补充。赞分享构建工具开发工具CLI【免费下载链接】msbuildThe Microsoft Build Engine (MSBuild) is the build platform for .NET and Visual Studio.项目地址https://gitcode.com/gh_mirrors/ms/msbuild点击查看免费下载相关推荐Claude Task Master 智能任务扩展expand-task将复杂任务拆解为可执行子任务Claude Task Master 智能任务扩展expand task将复杂任务拆解为可执行子任务 导读 本文以 Claude Task MasterAI Agent开发工具CLIMCPoneTBB 任务调度器Task Scheduler完全指南任务模型、调度控制与 task_group / task_arena 编程接口oneTBB 任务调度器Task Scheduler完全指南任务模型、调度控制与 task_group / task_arena 编程接口 导读 oneA并发编程高性能计算Eclipse Theia 任务扩展theia/task实战指南从 tasks.json 配置到源码级任务执行机制Eclipse Theia 任务扩展theia/task实战指南从 tasks.json 配置到源码级任务执行机制 theia/task 是 EcliIDE代码编辑器开发工具前端桌面应用插件系统后端AI 应用上一篇LAV Filters免费解码器完整指南让Windows视频播放更流畅的终极方案下一篇LAV FiltersWindows媒体播放的终极免费开源解码解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
` 机制与 1000 倍加速解析)
