添加和修改工作项字段以支持报告

  • 项目

可以使用工作项字段来跟踪工作项类型的数据、定义查询的筛选条件并在报表中使用。 对于要在报表中显示的任意字段（系统字段除外）将跟踪的工作项类型，您必须在定义文件中定义该字段。 系统会自动为每个工作项类型定义系统字段。 但必须将系统字段包含在工作项窗体中才能支持数据输入。

若要支持报告，可以添加字段或更改现有字段的特性。 添加或修改字段时，您将应用系统命名约定以确保按逻辑将数据分组到 SQL Server Analysis Services 多维数据集中的各个文件夹。

主题内容

  • 最佳做法

  • 使用现有字段

  • 列出为团队项目集合定义的字段

  • 可报告字段特性

  • 更改字段的可报告特性

  • 添加字段以支持报告

  • 验证对可报告字段特性所做的更改

  • 分配报告引用名称时的最佳做法

对于该默认值定义的可报告字段列表中的过程模板，请参见 Visual Studio ALM 的可报告字段参考。

最佳做法

在添加或修改字段之前，请查看以下最佳做法：

  • 确定您是否能使用包含团队项目的团队项目集合中已定义的某个字段。 通过使用现有字段，可支持跨项目报告。

  • 确定是否可以使用在 Visual Studio Team Foundation Server的部署的另一个项目集合中定义的字段。通过使用现有字段，可支持跨项目报告。

  • 在整个 Team Foundation Server 部署中，每个项目集合中的字段数不能多于 1,024，所有项目集合中的唯一可报告字段数不能多于 1,024。 已合并字段将计为一个可报告字段。

  • 制定一个标准程序和评审过程来在过程模板、团队项目或项目集合中添加和修改字段。

  • 在标记要报告的字段时使用系统命名约定。 当您在 Team Foundation Server 部署中按系统方式跨所有团队项目集合分配引用名称时，需要确保一致性和可用性更高的仓库和多维数据集架构，并避免仓库中发生架构冲突。 有关更多信息，请参见解决数据仓库中发生的架构冲突。

    您最多可为一个工作项字段分配四个标记特性：

    备注

    未为 Microsoft Solutions Framework 过程模板中定义的字段分配报告名称或报告引用名称。默认情况下，将使用引用名称和名称特性。

    • name. 工作项查询的下拉菜单中显示的字段的友好名称。 在团队项目中定义的所有字段中，友好名称必须是唯一的。 此外，友好名称可能与分配给工作项窗体上的字段的显示标签不同。 有关更多信息，请参见Control XML 元素引用。

    • refname. 分配给某个字段的唯一标签，它用于将该字段与团队项目集合中定义的所有其他字段区分开来。 无法更改分配给 refname 的值。

      有关字段的友好名称和引用名称的要求和限制，请参见工作项跟踪对象的命名约定。

    • reportingname. 可选特性。 用于标识报表中的字段的名称。 在未显式设置时，将使用分配给 name 特性的值。

    • reportingrefname. 可选特性。 分配给某个可报告字段的唯一标签，它用于将该字段与所有团队项目集合中定义的所有其他可报告字段区分开来。 在未显式设置时，将使用分配给 refname 特性的值。 有关建议的命名约定，请参见本主题后面的分配报告引用名称时的最佳做法。

      备注

      报告引用名称仅在数据透视表或 Analysis Services 多维数据集中可见。

使用现有字段

如果某个已定义的字段与要跟踪或报告的信息匹配，则应使用该字段。 若要使用现有字段，请执行下列步骤：

  • 标识要使用的字段。 使用 witadmin listfields 命令标识为所有项目集合定义的字段及其特性。 有关更多信息，请参见本主题后面的列出为团队项目集合定义的字段。

  • 确定字段是否为可报告字段以及可报告特性是否满足您的报告需求。

  • 如果字段不是可报告字段，则使用 witadmin changefield 更改该字段用于的项目集合的可报告特性。 有关更多信息，请参见本主题后面的更改字段的可报告特性。

  • 对于未定义字段的项目集合，将字段添加到要用来跟踪数据的工作项类型的 XML 定义文件中。 有关更多信息，请参见本主题后面的添加字段以支持报告。

列出为团队项目集合定义的字段

您可以使用 witadmin listfields 命令列出字段及其特性。 您可列出指定字段或项目集合中定义的所有字段。 witadmin listfields 命令的语法如下：

witadmin listfields /collection:CollectionURL /n:RefName

有关更多信息，请参见管理工作项字段 [witadmin]。

可报告字段特性

可报告字段具有的 reportable 特性值为 Detail、Dimension 或 Measure。 以下特性确定如何将工作项字段导出到数据仓库数据库并进行处理：

  • reportingtype. 若要在报表中包含某个字段，您必须为 reportable 特性分配下列值之一：

    • 分配 Detail 可将字段导出到关系仓库数据库，而非多维数据集。 如以下示例所示，Detail 类型仅用于 Integer、Double、String 或 DateTime 字段：

      <FIELD refname="MyCorp.Summary" name="Summary" type="String" reportable="detail">

    • 分配 Dimension 可将字段导出到关系仓库数据库和多维数据集。 如以下示例所示，Dimension 类型仅用于 Integer、Double、String 或 DateTime 字段。 此值对包含用于筛选报表的字段（例如，具有有效值列表的字段）很有用。

      <FIELD refname="MyCorp.Category" name="Category" type="String" reportable="dimension">

    • 分配 Measure 可支持处理多维数据集中预先计算的值。 Measure 类型仅用于 Integer 和 Double 字段。

      当您分配 Measure 作为 reportingtype 时，您必须分配 sum 作为 formula，如以下示例所示：

      <FIELD refname="MyCorp.Cost" name="Cost" type="Integer" reportable="measure" formula="sum">

  • reportingrefname. 可以为标记为可报告的字段分配一个不同的引用名称。 如果未指定任何值，则将使用分配给 refname 特性的值。

    可以使用此特性来合并或分离报告中包含的字段。 若要合并两个具有不同的引用名称且在不同的项目集合中定义的字段，请为这两个字段分配同一 reportingrefname。 若要分离两个具有相同的引用名称但在不同的项目集合中定义的字段，请为每个字段分配一个不同的 reportingrefname。

    您应尽可能合并字段以最大程度地减少仓库中的字段数，并遵循 1024 个可报告字段的最大限制。 您可以生成带合并字段的跨组报表。

  • reportingname. 可以为用于显示报表数据的字段分配一个不同的标签。 如果未指定任何值，则将使用分配给 name 特性的友好名称。 分配给 reportingname 的值将显示在多维数据集中。 分配给 reportingrefname 的值不会出现。

    重要

    您应使用最佳做法来标记报告字段，以便在数据透视表中将这些字段归为一组。有关更多信息，请参见分配报告引用名称时的最佳做法。

更改工作项字段的可报告特性

可以通过更改为项目集合定义的字段的特性赋值，将现有字段变为可报告字段。 一个或多个工作项类型定义中定义的现有字段。 此外，可以更改用于确定数据仓库中处理字段的方式的所有特性。

可以使用以下一系列步骤来更改字段的特性赋值：

  1. 可以使用 witadmin changefield 命令更改字段的特性赋值。 对团队项目集合使用此命令。 使用下列语法：

    witadmin changefield /collection:CollectionURL /n:RefName [/name:NewName] [/syncnamechanges:true | false] [/reportingname:ReportingName] [/reportingrefname:ReportingRefName] [/reportingtype:Type] [/reportingformula:Formula] [/noprompt]

    若要将现有字段变为可报告字段，请更改报告类型。 例如，若要使 AW.Common.TeamPriority 字段可用于筛选报表，请为其分配 Dimension 值：

    witadmin changefield /collection:http://AdventureWorksServer:8080/AWTeam/Collection1 /n:AW.Common.TeamPriority /reportingtype:dimension

    有关更多信息，请参见管理工作项字段 [witadmin]。

  2. （可选）如果您有多个项目集合，则您可能需要对该集合中定义的工作项字段进行类似更改。 若要在将数据导出到数据仓库数据库并进行处理时避免架构冲突，您必须为所有集合中的这些特性分配相同的值：

    • 字段类型（无法为现有字段更改此字段的值）。

    • 报告类型。

    • 报告名称。

    有关更多信息，请参见解决数据仓库中发生的架构冲突。

  3. 在对要用于报告的工作项字段进行所有更改后，您必须处理数据仓库数据库。 您可使用 ProcessWarehouse 和 ProcessAnalysis Web 服务（可通过 WarehouseControlWebService 获取这些服务）。

    此步骤可确保报表使用者在您更改字段特性时不会看到错误。

    有关更多信息，请参见管理工作项字段 [witadmin]。

添加字段以支持报告

您可向一个或多个工作项类型的定义中添加字段。 在添加字段时，您应向字段将支持其报告的所有工作项类型添加相同的字段元素定义。 如果您希望字段支持跨项目报告，则应将该字段添加到将报告的所有团队项目中的所有工作项类型。

有关更多信息，请参见使用工作项字段。

验证对可报告字段特性所做的更改

可以通过按需处理数据仓库，然后检查报表以验证是否已更新这些报表，来验证对可报告字段特性所做的更改。 或者，您可以选择等待，直到仓库适配器作业运行。 默认情况下，每隔几分钟处理一次关系数据库。 而默认情况下，每隔两小时处理一次多维数据集。

备注

有关 WarehouseControlWebService的更多信息，请 手动处理数据仓库和 analysis services 多维数据集 Team Foundation server 的参见。

  1. 通过使用 ProcessWarehouse WarehouseControlWebService 按需处理关系数据仓库。

  2. 通过使用 ProcessAnalysisDatabase WarehouseControlWebService 按需处理多维数据集。

  3. 验证是否正在更新报表。 通过面板或报表管理器查看报表。 有关更多信息，请参见面板（敏捷）或报表 (Agile)。

分配报告引用名称时的最佳做法

对于报告引用名称，您必须分配标签，以便您能在数据透视表和多维数据集中轻松查找字段。 通过应用系统命名约定以便按逻辑顺序对字段进行分组，来做到这一点。 另外，如果未按照有效方式对字段进行分组，则可更改字段的报告引用名称。

应用系统命名约定变得越来越重要，因为系统会将所有项目集合中定义的所有团队项目中的所有可报告数据写入单个关系数据仓库。 随后将对来自该仓库的数据进行处理，并将其写入多维数据集。 由于每个项目集合的工作项字段是分开管理的，因此可能会应用不同的标签，这可能会导致未正确组织一组字段以支持创作报表。

具有可报告维度类型的工作项字段对应于多维数据集中的维度特性。 维度特性归类到不同的文件夹，这些文件夹基于过程模板或工作项类型定义中分配的报告引用名称。 类型映射如下：

  • 具有“System”前缀的字段是内部字段，将在“工作项”维度下直接列出这些字段，并在其前面添加“Work Item”。

  • 其他字段置于其名称与引用名称中的前缀对应的文件夹下。 例如，具有“Microsoft.VSTS.Common”前缀的字段列在标记为“Microsoft VSTS Common”的文件夹下。

如下图所示，已为共享公共前缀的字段的每个前缀组添加一个文件夹：

OLAP 多维数据集中的文件夹结构

下表列出了其引用名称以“System”开头并在数据透视表中以“Work Item”为前缀列出的字段。这些字段将置于“工作项”维度的正下方。 所有其他字段置于其名称与引用名称中的前缀对应的文件夹下。

备注

未使用企业版的 SQL Server Analysis Services 的部署无权访问由此版本提供的转换功能。在这些部署中，字段由其在多维数据集中的完全引用名称标识，“.”将替换为“_”（例如，“System_Id”和“System_Title”）。

数据透视表和多维数据集中的名称

引用名称

数据类型

Work Item.Area Path

System.AreaPath

TreeType

Work Item.Assigned To

System.AssignedTo

字符串

Work Item.Changed By

System.ChangedBy

字符串

Work Item.Changed Date

System.ChangedDate

DateTime

Work Item.Created By

System.Created By

字符串

Work Item.Created Date

System.CreatedDate

DateTime

Work Item.ID

System.Id

Integer

Work Item.Iteration Path

System.IterationPath

TreeType

Work Item.Previous State

System.PreviousState

字符串

Work Item.Reason

System.Reason

字符串

Work Item.Rev

System.Rev

Integer

Work Item.State

System.State

字符串

Work Item.Title

System.Title

字符串

Work Item.Work Item Type

System.WorkItemType

字符串

下表列出了在“工作项”维度下标记为“Microsoft.VSTS.Common”的文件夹中的数据透视表中出现的字段。 这些字段具有以“Microsoft.VSTS.Common”开头的引用名称。

数据透视表和多维数据集中的名称

引用名称

数据类型

Work Item.Activated By

Microsoft.VSTS.Common.ActivatedBy

字符串

Work Item.Activated Date

Microsoft.VSTS.Common.ActivatedDate

DateTime

Work Item.Closed By

Microsoft.VSTS.Common.ClosedBy

字符串

Work Item.Closed Date

Microsoft.VSTS.Common.ClosedDate

DateTime

Work Item.Created By

Microsoft.VSTS.Common.CreatedBy

字符串

Work Item.Created Date

Microsoft.VSTS.Common.CreatedDate

DateTime

Work Item.Resolved By

Microsoft.VSTS.Common.ResolvedBy

字符串

Work Item.Resolved Date

Microsoft.VSTS.Common.ResolvedDate

DateTime

Work Item.Resolved Reason

Microsoft.VSTS.Common.ResolvedReason

字符串

Work Item.Priority

Microsoft.VSTS.Common.Priority

Integer

Work Item.Severity

Microsoft.VSTS.Common.Severity

字符串

Work Item.Stack Rank

Microsoft.VSTS.Common.StackRank

Double

请参见

参考

管理工作项字段 [witadmin]

概念

解决数据仓库中发生的架构冲突

工作项字段参考 (Visual Studio ALM)

为 Visual Studio ALM 创建、自定义和管理报表

其他资源

定义工作项字段