分析 ClearQuest 数据库
更新：2007 年 11 月
在分析阶段，转换器从 ClearQuest 数据库读取架构，并生成以 Team Foundation 格式表示该架构的文件。转换器使用 ClearQuest 查询来确定 ClearQuest 基实体类型；ClearQuest 中的一个查询基于一个实体类型。转换器还查找与基实体类型相关联的实体类型。基实体的关联实体是指基实体所引用的实体。这意味着这些实体在基实体类型中以引用或引用列表的形式存在。被引用实体的列表中不包含以下内容：
可能作为“副本”被引用的实体类型。
用户实体 用户是根据 Team Foundation 中的用户处理来迁移的。Team Foundation 不将用户作为实体处理。
附件实体 附件是根据 Team Foundation 的核心附件处理来迁移的。Team Foundation 不将附件作为实体处理。
历史记录 历史记录是按照 Team Foundation 的核心历史记录处理来迁移的。Team Foundation 不将历史记录作为实体处理。
组 转换器不迁移 ClearQuest 组。组在 Team Foundation 中以不同方式处理。
Ratl_replicas 此实体在 Team Foundation 中没有等效概念。
分析阶段
在 Visual Studio 2008 命令提示处，运行下面的命令：
CQConverter /c:analyze /m:CqConverterConfig.xml
.gif "说明") 说明： |
|---|
若要分析 ClearQuest 数据库，CqConverterConfig.xml 文件中指定的用户 ID 必须具有“超级用户”权限。有关更多信息，请参见 ClearQuest Administrator's Guide（《ClearQuest 管理员指南》）。而且您必须是指定 Team Foundation Server 上“Service Accounts”组的成员。有关更多信息，请参见 Team Foundation Server 权限。 |
ClearQuest 转换器可能需要几分钟才能完成运行。分析阶段结束时将生成若干文件。
转换器配置文件
必须在配置文件中指定转换器输入。有关更多信息，请参见工作项转换器配置文件。
输出文件
分析阶段生成若干输出文件。这些文件保存到由迁移设置文件中的 <Outputdirectory> 元素指定的文件夹中。如果未指定任何目录，则转换器将创建一个与 ClearQuest 基实体类型具有相同名称的文件夹。如果该文件夹已存在，将用新生成的 xml 文件覆盖该文件夹的内容。
分析阶段结束时将创建下列文件：
工作项类型定义 xml 文件 这些文件以 Team Foundation 格式表示工作项类型，且用于创建 Team Foundation 中的工作项类型。为主要实体及每个被引用的实体生成一个文件。这些文件名为 <EntityType>.xml。例如，缺陷的工作项类项将生成文件 Defect.xml。
字段映射 xml 文件 这些文件指定如何将字段从 ClearQuest 记录类型映射到 Team Foundation 工作项类型以及要在数据迁移期间应用的任何数据转换。这些文件与工作项类型文件具有一对一的关系。每个字段映射文件指定相应工作项类型的映射。这些文件名为 <EntityName>FieldMap.xml。例如，缺陷的工作项类型将生成文件 DefectFieldMap.xml。
用户映射 xml 文件 此文件名为 UserMap.xml。它指定如何将 ClearQuest 的用户映射到 Team Foundation 用户。此文件可能是必需的，因为 ClearQuest 具有单独的用户数据库，而 ClearQuest 用户名可能与 Windows 用户帐户不同。Team Foundation 需要 Windows 用户帐户。
架构映射 xml 文件 此文件名为 SchemaMap.xml。该文件包含以上所述的所有文件的名称并指定工作项类型与关联文件之间的附加映射。
分析报表 xml 文件 此文件名为 CQAnalysisReport.xml。此文件将附带生成名为 _AnalysisReport_Files 的文件夹，该文件夹包括图像和样式表以便在浏览器中正确显示此文件。
名为 CQConverter.log 的日志文件
说明：无论查询中选定的特定工作项的字段数是多少，转换器将选择工作项类型中存在的所有字段进行分析。这些输出文件包含所有字段的引用。
工作项类型定义文件
工作项类型定义 (WITD) 文件以 Team Foundation 格式捕获工作项类型的架构。可以用 WITD 文件在 Team Foundation 中创建新的工作项类型。WITD 文件指定工作项类型中的字段、状态和状态转换、规则以及用于显示工作项的用户界面。有关工作项类型定义文件的更多信息，请参见 自定义工作项类型。
下面各节将详细介绍这些工作项类型是如何生成的。
字段类型映射
转换器将 ClearQuest 中的字段类型映射到 Team Foundation 中相应的字段类型。下表指定如何映射这些字段。
ClearQuest 字段类型 |
Team Foundation 字段类型 |
|---|---|
ATTACHMENT_LIST |
不适用。这种类型的字段在 Team Foundation 中将作为附件而非字段进行迁移。 |
DATE_TIME |
DateTime |
INT |
Integer |
MULTILINE_STRING |
Plain Text |
REFERENCE |
不适用。这种类型的字段在 Team Foundation 中将作为链接而非字段进行迁移。 |
REFERENCE_LIST |
不适用。这种类型的字段在 Team Foundation 中将作为链接而非字段进行迁移。 |
SHORT STRING |
String |
DBID |
未迁移。这种类型的字段是为 ClearQuest 中的系统字段保留的，而在迁移的工作项中不是必需的。 |
ID |
String。这种类型的字段在 Team Foundation 中将作为“vsts sourceid”字段进行迁移。 |
JOURNAL |
不适用。这种类型的字段是为 ClearQuest 中的系统字段保留的，并迁移为 Team Foundation 中的历史记录。 |
State |
String。这种类型的字段是为 ClearQuest 中的系统字段保留的，并迁移为 Team Foundation 中的“State”系统字段。 |
字段映射
ClearQuest 中的每个工作项类型都使用系统字段，同样，Team Foundation 工作项类型中也有系统字段。转换器将 ClearQuest 的系统字段相应地映射到 Team Foundation 中的系统字段。除系统字段之外，还存在通常可以在 ClearQuest 工作项类型中找到的字段。转换器会将它们相应地映射到 Team Foundation 字段。
下表指定转换器如何映射系统字段。
ClearQuest 系统字段 |
Team Foundation 系统字段 |
|---|---|
ID |
vsts sourceid |
State |
状态 |
下表指定转换器如何映射公共字段。
ClearQuest 字段 |
Team Foundation 系统字段 |
|---|---|
Headline |
标题 |
Description |
说明 |
Submitter |
创建者 |
Submit_Date |
创建日期 |
Owner |
指派给 |
User_name (History) |
更改者 |
action_timestamp (History) |
更改日期 |
字段行为的处理
可以指定 ClearQuest 中的字段上的行为。还可以为工作项的不同状态上的字段指定不同的行为。转换器对于 ClearQuest 工作项中的迁移行为有限制。例如，转换器只迁移初始状态（即新建工作项的状态）上指定的字段行为。
分析阶段中不分析或生成为不同的状态定义的行为。然而，Team Foundation 支持对这些行为的指定，而且您可以在分析阶段后在工作项类型中手动添加这些行为。有关自定义 Team Foundation 中工作项类型的行为的更多信息，请参见定义工作项工作流程。
下表指定了工作项行为的迁移。
行为 |
说明 |
|---|---|
Mandatory |
此行为迁移到 Team Foundation。Mandatory 是在 Team Foundation 中通过应用工作项类型定义中的 <REQUIRED> 元素来指定的。 |
Optional |
此行为迁移到 Team Foundation。Optional 是 Team Foundation 中的字段的默认行为，因此工作项类型定义中不需要任何其他元素。 |
Read-only |
此行为未迁移。 |
Use_hook |
此行为未迁移。 |
工作项类型中由转换器添加的字段
除 ClearQuest 工作项类型中存在的字段外，转换器还在每个工作项类型中生成以下字段。
转换器操作所需的字段
不要移除这些字段。从工作项类型移除这些字段会导致迁移失败。如果不要显示这些字段，可以从工作项用户界面（窗体）移除它们。我们建议将这些字段保持为只读，以防止用户进行编辑。这些字段如下所示：
迁移的工作项的 ClearQuest ID 的字段。
<FIELD name="vsts sourceid" refname="Microsoft.TeamFoundation.Converters.vsts_sourceid" type="String"/>迁移的工作项所出自的 ClearQuest 数据库的字段。
<FIELD name="vsts sourcedb" refname="Microsoft.TeamFoundation.Converters.vsts_sourcedb" type="String"/>用于跟踪特定工作项的迁移状态的字段。
<FIELD name="Migration Status" refname="Microsoft.TeamFoundation.Converters.Migration_Status" type="String"/>Team Foundation 中的系统字段。当 Team Foundation 中的系统字段映射到 ClearQuest 中的系统字段时，会生成相应的映射 xml。Team Foundation 中的一些系统字段不映射到 ClearQuest 中的系统字段并在每个工作项类型中生成附加字段。这些字段使用与以下 xml 类似的注释来标识：
<!--State is a core field in Team Foundation Work Item Tracking and we recommend that you use this field because it best suits the purpose-->
列表字段的处理
ClearQuest 中的字段可能具有一组为其定义的有效或建议值。当转换器读取这些字段及其类型时，还会收集字段是否为列表字段类型的信息。如果字段是列表字段类型，则转换器还会收集有效的或建议的列表值。此信息是在工作项类型定义文件中对应的字段部分中捕获的。查找元素“<AllowedValues>”或“<SugggestedValues>”。
状态和状态转换的处理
ClearQuest 架构中基于状态的实体类型定义支持以下内容：
状态集。
状态之间的转换称为“操作”。
与状态相关联的字段行为。
转换器捕获 ClearQuest 的状态和操作，作为 Team Foundation 工作项类型定义中的状态和状态转换。
工作项窗体的处理
转换器不会将 ClearQuest 数据库的窗体信息迁移到 Team Foundation。转换器将生成默认的工作项窗体，作为分析阶段期间所生成的架构的一部分；然而，此默认窗体与 ClearQuest 中的原始窗体没有任何相似之处。该默认窗体包含的格式设置很少，而且几乎始终需要进行编辑才能成为更可用的工作项布局。有关如何编辑工作项窗体的信息，请参见 定义工作项表单。
窗体上的控件
除了 Team Foundation，还可以在 ClearQuest 中的工作项窗体上放置各种控件。Team Foundation 支持可使用的一组预定义控件。ClearQuest 中可用的一些控件在 Team Foundation 中不可用。尽管迁移过程中保留了最大数据量，但可用控件中的差异会影响 Team Foundation 中的窗体上的数据显示。以下控件在 Team Foundation 中不受支持。
ActiveX 控件
Calendar 控件
复选框控件 (Check Box)
组合框控件 (Combo Box)
重复基控件 (Duplicate Base)
重复依赖控件 (Duplicate Dependent)
父/子控件 (Parent/Child)
图片控件 (Picture Control)
下压按钮控件 (Push Button)
列表框控件 (List Box)
列表视图控件 (List view)
选项按钮控件 (Option Button)
静态文本框控件 (Static Text Box)
作为迁移计划的一部分，应该评估缺少这些控件可能对用户造成的影响。
字段映射文件
字段映射文件指定如何映射字段以及如何映射值。
字段映射
字段映射文件指定 ClearQuest 中的字段如何映射到 Team Foundation 中的字段。ClearQuest 中的大多数字段（除系统字段和公共字段以外）以一对一的方式映射到 Team Foundation。应将这些字段映射文件与对工作项类型定义文件中的字段所做的任何更改保持同步。例如，如果重命名工作项类型定义文件中的字段，则应更改映射文件以指定相同的映射。同样，如果从工作项类型定义文件删除一些字段，则也应从对应的字段映射文件删除这些字段。
值映射
字段映射文件还指定在迁移过程中要如何转换字段数据。默认情况下，不生成值映射。如果要在迁移过程中转换数据，可以指定值映射。可使用值映射指定这些转换，例如值“Pri1”应该映射到“1”。
字段映射文件是一个 XML 文件。下面的示例演示如何映射字段和值：
<?xml version="1.0"?>
<FieldMaps xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<!-- Title is a core field in Team Foundation Work Item Tracking and we recommend that you use this field because it best suits the purpose-->
<FieldMap from="Headline" to="Title" />
<FieldMap from="Submitter" to="Submitter">
<ValueMaps refer="UserMap" />
</FieldMap>
<!-- Created Date is a core field in Team Foundation Work Item Tracking and we recommend that you use this field because it best suits the purpose-->
<FieldMap from="Submit_Date" to="Created Date" />
<!-- Assigned To is a core field in Team Foundation Work Item Tracking and we recommend that you use this field because it best suits the purpose-->
<FieldMap from="Owner" to="Assigned To">
<ValueMaps refer="UserMap" />
</FieldMap>
</FieldMaps>
有关字段映射的更多信息，请参见字段映射文件架构。
映射到区域路径和迭代路径字段
Team Foundation 工作项跟踪将工作项组织成一个有结构的区域和迭代的层次结构。有关更多信息，请参见如何：修改团队项目区域和如何：修改团队项目迭代。
路径用于帮助对工作项进行结构分组，以表示您的团队从事的工作所针对的各种组件、项目或应用程序。迭代用于帮助根据里程碑和项目阶段等重要事件对工作项进行分组。区域路径和迭代路径系统字段在 Team Foundation 中定义此信息。由于 ClearQuest 没有这样的概念，因此转换器为这些字段提供了默认值；默认为所有工作项都位于区域路径和迭代路径的根。
尽管 ClearQuest 没有提供区域路径和迭代路径，但您可能正在以其他方式使用这些概念。例如，您的工作项类型中可能有某个字段，用来表示工作项所属的特定项目。这大致与区域路径的概念相对应。同样，您可能有名为“Fix By”的另一个字段，用来表示完成特定工作项的里程碑。请考虑将这些字段映射到区域路径和迭代路径，以便工作项显示在这些不同的节点中，而不是全部显示在一个根节点中。如先前部分所述，这些映射是在工作项类型字段映射文件中指定的。
下面的 XML 示例演示如何映射名为 Tree Path、可能值为 Area1 和 Area2 的 ClearQuest 字段。
<FieldMap from="Tree Path" to="Area Path" exclude="false">
<ValueMaps>
<ValueMap from="Area1" to="Area1" />
<ValueMap from="Area2" to="Area2" />
</ValueMaps>
</FieldMap>
下面的 XML 示例演示如何映射名为 Fix By、可能值为 Alpha 和 Beta 的 ClearQuest 字段。
<FieldMap from="Fix By" to="Iteration Path" exclude="false">
<ValueMaps>
<ValueMap from= "Alpha" to="Alpha"/>
<ValueMap from= "Beta" to="Beta"/>
</ValueMaps>
</FieldMap>
用户映射文件
用户映射文件指定如何在 ClearQuest 与 Team Foundation 之间映射用户。有关更多信息，请参见 用户映射文件架构。
架构映射文件
架构映射文件指定源工作项类型、目标工作项类型、工作项定义文件以及字段映射文件。有关更多信息，请参见如何：编辑架构映射文件。
分析报表文件
迁移结束时生成分析报表文件。迁移报表名为 CQAnalysisReport.xml，它是在运行 CQConverter 的文件夹中生成的。名为 _MigrationReport_Files 的关联文件夹包含图像文件和样式表，以在浏览器中显示报表。分析结束时，应打开此文件查看在分析阶段期间发现的任何错误或警告。分析报表显示以下内容：
**摘要 **关于分析运行的摘要信息。
**错误 **在分析运行期间发现的任何错误。您应对列出的所有错误采取更正措施。
**警告 **分析运行期间发现的任何警告。警告需要注意，但不一定必须修复。
输出 此部分列出已生成的输出文件。
日志文件
转换器生成名为 CQConverter.log 的日志文件。此文件用于调试，通常不必检查该文件。日志文件创建在运行 CQConverter 的文件夹中。它包含跟踪消息，可能有助于调试在转换器运行期间发现的问题。
通过设置 CQConverter.exe.config 文件中的 MinLevelForAllSource 属性的值，可控制跟踪级别。CQConverter.exe.config 文件与 CQConverter.exe 位于相同的文件夹中。可以将值设定在 1（最小跟踪量）到 4（最大跟踪量）之间。
| 说明： |
|---|
请注意，跟踪级别越高，转换器性能就越低，且日志文件可能变得很大。 |
错误文件
转换器还会生成一个文件，该文件包含转换器运行期间发现的所有错误。该文件名为 ConverterErrors.txt，它是在运行 CQConverter 的同一个文件夹中生成的。