如何：定义工作项链接处理程序

项目
06/09/2015

可以创建一个 Visual Studio 集成扩展，此扩展会在用户创建或删除 UML 模型元素与工作项之间的链接时进行响应。例如，当用户选择将新工作项链接到模型元素时，您的代码会利用模型中的值初始化工作项的字段。

设置 UML 扩展解决方案

这使您能够开发处理程序，然后将它们分发给其他用户。需要设置以下两个 Visual Studio 项目：

一个包含链接处理程序的代码的类库项目。
一个充当用于安装命令的容器的 VSIX 项目。如果需要，可以将其他组件包括在同一 VSIX 中。

设置 Visual Studio 解决方案

创建一个类库项目（通过在现有 VSIX 解决方案中添加一个类库项目或创建一个新的解决方案）。
1. 在**“文件”菜单上，选择“新建”和“项目”**。
2. 在**“已安装的模板”下，展开“Visual C#”或“Visual Basic”，然后在中间列中单击“类库”**。
3. 设置**“解决方案”**以指示您是希望创建新的解决方案，还是希望向已打开的 VSIX 解决方案添加组件。
4. 设置项目的名称和位置，然后单击“确定”。
除非解决方案中已有一个 VSIX 项目，否则请创建一个 VSIX 项目。
1. 在解决方案资源管理器的快捷菜单上，选择添加，新建项目。
2. 在**“已安装的模板”下，展开“Visual C#”或“Visual Basic”，然后选择“扩展性”。在中间列中，选择“VSIX 项目”**。
将 VSIX 项目设置为解决方案的启动项目。
- 在“解决方案资源管理器”中，从VSIX项目的快捷菜单上选择设为启动项目。
在 source.extension.vsixmanifest 中的**“内容”**下，将类库项目添加为 MEF 组件。
1. 在MetaData 选项卡上，为 VSIX 设置一个名称。
2. 在安装目标选项卡上，将 Visual Studio 旗舰版、高级专业版设为目标。
3. 在资产选项卡中，选择新建，然后在对话框中，设置：
  
  类型 = MEF组件
  
  源 = 当前解决方案中的项目
  
  项目 = Your class library project

定义工作项链接处理程序

执行类库项目中的下列所有任务。

项目引用

将以下 .NET 程序集添加到项目引用：

Microsoft.TeamFoundation.WorkItemTracking.Client.dll

Microsoft.VisualStudio.TeamFoundation.WorkItemTracking.dll Microsoft.VisualStudio.Modeling.Sdk.12.0

Microsoft.VisualStudio.ArchitectureTools.Extensibility.Uml

Microsoft.VisualStudio.Uml.Interfaces

System.ComponentModel.Composition

System.Drawing - 由代码示例使用

如果在**“添加引用”对话框的“.Net”**选项卡下找不到上述引用中的某个引用，请使用“浏览”选项卡在 \Program Files\Microsoft Visual Studio 12.0\Common7\IDE\PrivateAssemblies\ 中查找该引用。

导入工作项命名空间

在 Visual Studio 项目的**“引用”**中，添加对以下程序集的引用：

Microsoft.TeamFoundation.WorkItemTracking.Client.dll
Microsoft.VisualStudio.TeamFoundation.WorkItemTracking.dll

在程序代码中，导入以下命名空间：

using System.ComponentModel.Composition;
using Microsoft.VisualStudio.Uml.Classes;
using Microsoft.VisualStudio.ArchitectureTools.Extensibility.Uml;
using Microsoft.VisualStudio.TeamFoundation.WorkItemTracking;
using System.Linq;

定义链接工作项的事件处理程序

将类文件添加到类库项目中，并设置其内容，如下所示。根据您的喜好更改命名空间和类名。

using System.ComponentModel.Composition;
using Microsoft.VisualStudio.Uml.Classes;
using Microsoft.VisualStudio.ArchitectureTools.Extensibility.Uml;
using Microsoft.VisualStudio.ArchitectureTools.Extensibility.Presentation;
using Microsoft.VisualStudio.TeamFoundation.WorkItemTracking;
using System.Linq;


namespace WorkItems
{
  [Export(typeof(ILinkedWorkItemExtension))]
  public class MyWorkItemExtension : ILinkedWorkItemExtension
  {
    // Called before a new work item is edited by the user.
    // Use this to initialize work item fields from the model element.
    public void OnWorkItemCreated(System.Collections.Generic.IEnumerable<IElement> elementsToBeLinked, IWorkItemDocument workItemDocument)
    {
      INamedElement namedElement =
            elementsToBeLinked.First() as INamedElement;
      if (namedElement != null)
        workItemDocument.Item.Title = namedElement.Name;

    }

    // Called when any work item is linked to a model element.
    public void OnWorkItemLinked(System.Collections.Generic.IEnumerable<IElement> elements, string serverUri, int workItemId)
    {
      foreach (IElement element in elements)
        foreach (IShape shape in element.Shapes())
          shape.Color = System.Drawing.Color.Red;
    }

    // Called when a work item is unlinked from a model element.
    public void OnWorkItemRemoved(IElement element, string serverUri, int workItemId)
    {
      foreach (IShape shape in element.Shapes())
        shape.Color = System.Drawing.Color.White;
    }
  }
}

测试链接处理程序

仅为测试目的在调试模式下执行链接处理程序。

测试链接处理程序

按F5，或在“调试”菜单上选择“开始调试”。

这将启动 Visual Studio 的实验实例。

疑难解答：如果新的 Visual Studio 未启动，请确保将 VSIX 项目设置为解决方案的启动项目。
在实验性 Visual Studio 中，打开或创建一个建模项目，然后打开或创建一个建模图。
创建一个模型元素（如 UML 类）并设置其名称。
右击该元素，然后单击**“创建工作项”**。
- 如果子菜单显示**“打开 Team Foundation Server 连接”，请单击它，并按照对话框中的提示操作以连接到服务器。然后再次右击该模型元素，并单击“创建工作项”**。
- 如果子菜单显示工作项类型的列表，请单击其中一个工作项。
  
  这将打开一个新的工作项窗体。
如果已使用上一节中的代码示例，请确认工作项标题与模型元素相同。这说明 OnWorkItemCreated() 已起作用。
完成此窗体，保存并关闭该工作项。
验证该工作项现在是否显示为红色。此操作演示代码示例中的 OnWorkItemLinked()。

疑难解答：如果处理程序方法未运行，请确认：
- 该类库项目作为一个 MEF 组件在 VSIX 项目的 source.extensions.manifest 中的**“内容”**列表中列出。
- 正确的 Export 特性将附加到处理程序类，而此类实现 ILinkedWorkItemExtension。
- 所有 Import 和 Export 特性的参数都有效。

关于工作项处理程序代码

侦听新工作项

在用户选择创建要链接到模型元素的新工作项时，将调用 OnWorkItemCreated。您的代码可以初始化工作项字段。然后，工作项将呈现给用户，用户可以更新字段并保存工作项。在成功保存工作项之前，不会创建指向模型元素的链接。

  public void OnWorkItemCreated(
      IEnumerable<IElement> elementsToBeLinked,
      IWorkItemDocument workItem)
  {
    INamedElement namedElement = 
           elementsToBeLinked.First() as INamedElement;
    if (namedElement != null)
        workItem.Item.Title = namedElement.Name;
  }

侦听链接创建

在创建链接后，将会立即调用 OnWorkItemLinked。无论链接指向新的工作项还是现有项，都将调用它，而且只为每个工作项调用它一次。

public void OnWorkItemLinked
        (IEnumerable<IElement> elements, 
         string serverUri, // TFS server
         int workItemId)
{
  foreach (IElement element in elements)
    foreach (IShape shape in element.Shapes())
         shape.Color = System.Drawing.Color.Red;
}

备注

若要使此示例起作用，则必须添加对 System.Drawing.dll 的项目引用，并导入命名空间 Microsoft.VisualStudio.ArchitectureTools.Extensibility.Presentation。但是，OnWorkItemLinked 的其他实现并不需要这些添加的内容。

侦听链接移除

在删除每个工作项链接之前，都将调用 OnWorkItemRemoved 一次。如果删除某个模型元素，则将移除该元素的所有链接。

public void OnWorkItemRemoved
         (IElement element, string serverUri, int workItemId)
{...}

更新工作项

可以使用 Team Foundation 命名空间来操作工作项。

若要使用以下示例，请将这些 .NET 程序集添加到项目的引用中：

Microsoft.TeamFoundation.Client.dll
Microsoft.TeamFoundation.WorkItemTracking.Client.dll

using Microsoft.TeamFoundation.Client;
using Microsoft.TeamFoundation.WorkItemTracking.Client;
...
public void OnWorkItemLinked
        (IEnumerable<IElement> elements, 
         string serverUri, // TFS server
         int workItemId)
{
  TfsTeamProjectCollection tfs =
        TfsTeamProjectCollectionFactory
            .GetTeamProjectCollection(new Uri(serverUri));
  WorkItemStore workItemStore = new WorkItemStore(tfs);
  WorkItem item = workItemStore.GetWorkItem(workItemId);
  item.Open();
  item.Title = "something";
  item.Save();
}

访问工作项引用链接

可以访问链接，如下所示：

//Get:
string linkString = element.GetReference(ReferenceConstants.WorkItem);
// Set:
element.AddReference(ReferenceConstants.WorkItem, linkString, true);

linkString 的格式为：

string.Format(@"%{0}\{1}#{1}${2}", tfServer, projectCollection, RepositoryGuid, workItem.Id);

其中：

服务器的 URI 为：

http://tfServer:8080/tfs/projectCollection

用例在 projectCollection 中非常重要。

可通过 TFS 连接获取 RepositoryGuid：

TfsTeamProjectCollection tpc = TfsTeamProjectCollectionFactory...;
RepositoryGuid= tpc.InstanceId;

有关引用的更多信息，请参见如何：将引用字符串附加到模型元素。

请参见

参考

WorkItemStore

概念

通过

如何：定义工作项链接处理程序

设置 UML 扩展解决方案

设置 Visual Studio 解决方案

定义工作项链接处理程序

项目引用

导入工作项命名空间

定义链接工作项的事件处理程序

测试链接处理程序

测试链接处理程序

关于工作项处理程序代码

侦听新工作项

侦听链接创建

侦听链接移除

更新工作项

访问工作项引用链接

请参见

参考

概念

其他资源