在TFS 2015/2017中使用XAML UpgradeTemplate的兼容问题

问题背景 #

从TFS 2013升级到2015/2017后，继续使用UpgradeTemplate.xaml运行TFS 2005/2008风格的MSBuild Team Build（基于TFSBuild.proj）时，会触发命名空间歧义的编译错误，具体报错如下：

C:\Program Files (x86)\MSBuild\Microsoft\VisualStudio\TeamBuild\Microsoft.TeamFoundation.Build.targets (957): The following errors were encountered while processing the workflow tree: 'VisualBasicValue<LabelChildOption>': Compiler error(s) encountered processing expression "Microsoft.TeamFoundation.VersionControl.Client.LabelChildOption.Fail". 'LabelChildOption' is ambiguous in the namespace 'Microsoft.TeamFoundation.VersionControl.Client'. 'VisualBasicValue<RecursionType>': Compiler error(s) encountered processing expression "Microsoft.TeamFoundation.VersionControl.Client.RecursionType.Full". 'RecursionType' is ambiguous in the namespace 'Microsoft.TeamFoundation.VersionControl.Client'. C:\Program Files (x86)\MSBuild\Microsoft\VisualStudio\TeamBuild\Microsoft.TeamFoundation.Build.targets (957): The "Label" task failed unexpectedly. System.Activities.InvalidWorkflowException: The following errors were encountered while processing the workflow tree: 'VisualBasicValue<LabelChildOption>': Compiler error(s) encountered processing expression "Microsoft.TeamFoundation.VersionControl.Client.LabelChildOption.Fail". 'LabelChildOption' is ambiguous in the namespace 'Microsoft.TeamFoundation.VersionControl.Client'. 'VisualBasicValue<RecursionType>': Compiler error(s) encountered processing expression "Microsoft.TeamFoundation.VersionControl.Client.RecursionType.Full". 'RecursionType' is ambiguous in the namespace 'Microsoft.TeamFoundation.VersionControl.Client'. at System.Activities.Hosting.WorkflowInstance.ValidateWorkflow(WorkflowInstanceExtensionManager extensionManager) at System.Activities.Hosting.WorkflowInstance.RegisterExtensionManager(WorkflowInstanceExtensionManager extensionManager) at System.Activities.WorkflowApplication.EnsureInitialized() at System.Activities.WorkflowApplication.RunInstance(WorkflowApplication instance) at System.Activities.WorkflowApplication.Invoke(Activity activity, IDictionary`2 inputs, WorkflowInstanceExtensionManager extensions, TimeSpan timeout) at System.Activities.WorkflowInvoker.Invoke(Activity workflow, IDictionary`2 inputs, TimeSpan timeout, WorkflowInstanceExtensionManager extensions) at Microsoft.TeamFoundation.Build.Tasks.WorkflowTask.ExecuteInternal() at Microsoft.TeamFoundation.Build.Tasks.Task.Execute() at Microsoft.Build.BackEnd.TaskExecutionHost.Microsoft.Build.BackEnd.ITaskExecutionHost.Execute() at Microsoft.Build.BackEnd.TaskBuilder.<ExecuteInstantiatedTask>d__26.MoveNext()

这个问题的根源是TFS 2015+的核心程序集引入了破坏性变更，Microsoft.TeamFoundation.VersionControl.Client命名空间下重复定义了LabelChildOption和RecursionType枚举，导致XAML工作流无法解析正确的类型。虽然微软因为XAML构建已弃用不再官方支持，但我们有临时修复方案可以快速解决这个问题。

临时修复方案（无需重构旧构建） #

这个方案通过修改构建代理上的MSBuild目标文件，明确指定枚举的程序集版本来消除歧义：

• 在每个XAML构建代理上，打开路径C:\Program Files (x86)\MSBuild\Microsoft\VisualStudio\TeamBuild\Microsoft.TeamFoundation.Build.targets
• 定位到报错的第957行附近的<Label>任务代码块
• 将枚举引用从简单的命名空间路径，替换为带强命名信息的完整引用：
  • 把 Microsoft.TeamFoundation.VersionControl.Client.LabelChildOption.Fail 替换为：

    [Microsoft.TeamFoundation.VersionControl.Client.LabelChildOption, Microsoft.TeamFoundation.VersionControl.Client, Version=12.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a].Fail
    

  • 把 Microsoft.TeamFoundation.VersionControl.Client.RecursionType.Full 替换为：

    [Microsoft.TeamFoundation.VersionControl.Client.RecursionType, Microsoft.TeamFoundation.VersionControl.Client, Version=12.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a].Full
    

  提示：版本号12.0.0.0对应TFS 2013，如果你是从更早版本（比如TFS 2010）升级，需要调整为对应版本的程序集版本（TFS 2010是10.0.0.0，TFS 2012是11.0.0.0）

• 保存文件后，重新运行你的旧构建任务即可正常执行。

长期迁移建议 #

虽然临时修复能解决当前问题，但XAML构建已经被微软弃用，且旧版MSBuild Team Build不再受支持，建议你逐步迁移到TFS 2017支持的新构建系统：

• 先将旧的TFSBuild.proj转换为XAML构建定义
• 利用TFS内置的迁移工具，批量将XAML构建转换为新的经典构建或YAML构建
• 迁移完成后，你可以享受到新构建引擎的性能提升和更好的维护性

内容的提问来源于stack exchange，提问作者Derek Evermore