通过

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

  • 项目

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

设置 UML 扩展解决方案

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

  • 一个包含链接处理程序的代码的类库项目。

  • 一个充当用于安装命令的容器的 VSIX 项目。 如果需要，可以将其他组件包括在同一 VSIX 中。

设置 Visual Studio 解决方案

  1. 创建一个类库项目（通过在现有 VSIX 解决方案中添加一个类库项目或创建一个新的解决方案）。

    1. 在**“文件”菜单上指向“新建”，然后单击“项目”**。

    2. 在**“已安装的模板”下，单击“Visual C#”或“Visual Basic”，然后在中间列中单击“类库”**。

    3. 设置**“解决方案”**以指示您是希望创建新的解决方案，还是希望向已打开的 VSIX 解决方案添加组件。

    4. 设置项目的名称和位置，然后单击“确定”。

  2. 除非解决方案中已有一个 VSIX 项目，否则请创建一个 VSIX 项目。

    1. 在**“解决方案资源管理器”中，右击该解决方案，指向“添加”，然后单击“新建项目”**。

    2. 在**“已安装的模板”下，展开“Visual C#”或“Visual Basic”，然后单击“扩展性”。 在中间列中，单击“VSIX 项目”**。

  3. 将 VSIX 项目设置为解决方案的启动项目。

    • 在解决方案资源管理器中，右击该 VSIX 项目，然后单击**“设为启动项目”**。

  4. 在 source.extension.vsixmanifest 中的**“内容”**下，将类库项目添加为 MEF 组件。

    1. 打开 source.extension.vsixmanifest

    2. 单击**“添加内容”**。

    3. 在**“选择内容类型”处，选择“MEF 组件”**。

    4. 在**“选择源”处，单击“项目”**，并选择类库项目的名称。

  5. 单击**“选择版本”**，并选择要运行扩展的 Visual Studio 版本。

  6. 设置 VSIX 的名称字段和描述性字段。 保存该文件。

定义工作项链接处理程序

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

项目引用

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

Microsoft.TeamFoundation.WorkItemTracking.Client.dll

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

Microsoft.VisualStudio.ArchitectureTools.Extensibility.Uml

Microsoft.VisualStudio.Uml.Interfaces

System.ComponentModel.Composition

System.Drawing - 由代码示例使用

如果在**“添加引用”对话框的“.Net”**选项卡下找不到上述引用中的某个引用，请使用“浏览”选项卡在 \Program Files\Microsoft Visual Studio 10.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;
    }
  }
}

测试链接处理程序

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

测试链接处理程序

  1. 按 F5，或在**“调试”菜单上单击“开始调试”**。

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

    疑难解答：如果新的 Visual Studio 未启动，请确保将 VSIX 项目设置为解决方案的启动项目。

  2. 在实验性 Visual Studio 中，打开或创建一个建模项目，然后打开或创建一个建模图。

  3. 创建一个模型元素（如 UML 类）并设置其名称。

  4. 右击该元素，然后单击**“创建工作项”**。

    • 如果子菜单显示**“打开 Team Foundation Server 连接”，请单击它，并按照对话框中的提示操作以连接到服务器。 然后再次右击该模型元素，并单击“创建工作项”**。

    • 如果子菜单显示工作项类型的列表，请单击其中一个工作项。

      这将打开一个新的工作项窗体。

  5. 如果已使用上一节中的代码示例，请确认工作项标题与模型元素相同。 这说明 OnWorkItemCreated() 已起作用。

  6. 完成此窗体，保存并关闭该工作项。

  7. 验证该工作项现在是否显示为红色。 此操作演示代码示例中的 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;

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

请参见

任务

如何：将模型元素链接至工作项

参考

Microsoft.TeamFoundation.WorkItemTracking.Client.WorkItemStore

概念

使用 UML API 编程

其他资源

如何：将引用字符串附加到模型元素

如何：定义和安装建模扩展