ClearQuest 转换器疑难解答

  • 项目

更新：2007 年 11 月

如果在将工作项从 ClearQuest 迁移到 Team Foundation Server 时出现问题，则 ClearQuest 转换器将把错误和警告记入报告文件中。对问题进行故障诊断的最佳方法是查看报告文件以确定出现的问题。下面的信息在对 ClearQuest 转换器所发生的问题和错误进行故障排除时会有所帮助。

本节内容

分析问题疑难解答

未找到文件 license.dll

分析失败并且未创建分析报告

迁移问题故障排除

Migrate 命令失败

转换器连接时的严重错误

提供工作项类型时的严重错误

“分析报告”或“迁移报告”中的各个部分未展开

工作项架构更改未迁移到 Team Foundation Server

附件上载失败导致工作项迁移失败

分析问题疑难解答

如果运行 analyze 命令时出现问题，将向控制台报告错误，同时生成报告文件，其中包含有关所发生的问题的详细信息。多数情况下，您可以更正错误的起因，并重新启动转换器。如果不能确定错误的起因，则请在 Team Foundation 帮助中搜索错误号或确切的文本。某些错误还会列出转换器所使用的 ClearQuest API 所报告的内部错误。对于这些错误，可在 ClearQuest 文档中找到更多信息。

未找到文件 license.dll

运行 Analyze 命令时，您可能收到错误“没有找到 license.dll，因此这个应用程序未能启动 重新安装应用程序可能会修复此问题。” 单击“确定”后，您将收到另一条错误“TF61118: ClearQuest API 调用失败，出现以下错误: 检索 COM 类工厂中 CLSID 为 {94773112-72E8-11D0-A42E-00A024DED613} 的组件时失败，原因是出现以下错误: 8007007e。有关详细的帮助信息，请参考 ClearQuest 文档。”

当转换器由于库路径未正确配置而无法加载 ClearQuest 库时，则会发生这些错误。

解决方案

  • 检查计算机上是否安装了 ClearQuest 客户端。这将安装必要的库。

  • 请确保运行转换器的控制台窗口不是在安装 ClearQuest 之前启动的。若是，则打开新的控制台窗口，并再次运行转换器。

  • 确保在安装 ClearQuest 之后未修改 PATH 环境变量。PATH 环境变量应包含到由 ClearQuest 安装的 DLL 文件的路径。如果缺少这些路径，则可能必须重新安装 ClearQuest。

分析失败并且未创建分析报告

如果转换器未能加载配置文件，则 Analyze 命令将失败，并且不会创建任何报告。

解决方案

  • 使用 XML 编辑器或工具并验证配置文件 XML 格式是否正确。

  • 验证配置文件中的 XML 元素和属性是否已正确指定。如果收到验证错误，则错误消息将指示不支持的值，并将指示发现该值的行号。有关更多信息，请参见工作项转换器配置文件。

迁移问题故障排除

当转换器以 Migrate 命令运行时，有几个阶段可能发生错误。首先转换器读取配置文件，并使用指定的连接信息连接到 ClearQuest 数据库。接下来，转换器提供 Team Foundation Server 上的指定工作项类型。最后，转换器将工作项从 ClearQuest 迁移到 Team Foundation Server。

当转换器运行时，它会在控制台上显示状态消息。可使用这些状态消息确定迁移在哪个阶段失败。例如，如果最后一条成功状态消息为“正在验证 Team Foundation 中的用户”，则错误可能与用户映射文件有关。

迁移问题故障诊断的关键是检查任何报告的错误。错误是如下方式报告。

  1. 控制台上显示消息指示发生了错误。例如，如果有 2 条警告和 1 个错误，则您可能收到以下消息“迁移完成，有 2 个警告、1 个错误”。

  2. 同时将创建迁移报告文件，其中包含有关这些警告和错误的更具体的信息。报告文件的名称为 CQMigrationReport.xml。

说明：

某些情况下，转换器可能不会生成报告文件，您将只能看到输出到控制台上的错误消息。

Migrate 命令失败

迁移期间，转换器可能随时出现严重错误。严重错误将停止转换器并且不再迁移工作项。严重错误可能在工作项实际迁移之前发生，或者在某些工作项已迁移之后发生。迁移失败时，您将遇到下列两种症状之一：

  • 您将在迁移报告文件 CQMigrationReport.xml 中看到严重错误以及消息“迁移失败”。在该报告文件中，您将看到类似于下面的字符串：迁移失败 { 1 个严重错误 | 2 个错误 | 4 警告 }。

  • 迁移失败，有错误输出到控制台，但是没有报告生成。

解决方案

  • 修正错误源并重新启动转换器。重新启动转换器后，它不会重新迁移已经迁移的工作项。转换器不会创建重复的工作项。

  • 严重故障的起因各不相同，错误消息也是如此。大多数错误消息提供了标识错误原因的信息。通过在 Team Foundation 帮助中搜索错误文本还可找到更多有关某些错误的信息。最后，检查本主题前面所列出的对 Analyze 命令问题进行的故障诊断。很多相同的问题也适用于 Migrate 命令。

转换器连接时的严重错误

当转换器试图连接到 ClearQuest 或 Team Foundation Server 时可能发生严重错误。在指示连接问题的报告中将显示一条或多条错误消息。

解决方案

验证是否可通过 ClearQuest 客户端连接到 ClearQuest 以及是否可通过 团队资源管理器 连接到 Team Foundation Server。通常通过这些客户端发出的消息能较容易地诊断连接问题。此外，请记住，在登录时以将运行转换器的用户帐户身份启动这些客户端。这将缓存必要的数据以使转换器正确运行。

提供工作项类型时的严重错误

因为字段命名问题，可能会发生在提供工作项类型时发生的严重错误。您将遇到类似下面的错误消息：

“迁移失败，由于 TF61013: 转换器无法提供文件 \\<computername>\e$\temp\CQOGF\Defect.xml 中指定的工作项类型，因为出现以下错误: TF26177: 不能将字段 Microsoft.TeamFoundation.Converters.Priority_String 的名称从‘Priority String’重命名为‘Priority String1’。Team Foundation 不支持字段重命名。”

Team Foundation Server 中的字段有服务器级别的命名范围。字段的“名称”、“引用名”和“类型”在服务器上都应该是唯一的。转换器分析阶段有防止冲突的逻辑。当转换器检测到冲突时，它将相应修改生成的字段名。但是，从分析命令生成字段名到运行迁移命令，两者之间可能有时间间隔。在冲突之前的这段时间内，可能修改服务器上的工作项类型。或者，您可能编辑了已生成的工作项类型，并且无意中选择了与现有字段冲突的名称。

解决方案

  • 通过修改工作项类型的名称和/或引用名来解决冲突。通常情况下，可以直接使用已经存在的字段名称。若要查看现有工作项类型，必须从 Team Foundation Server 导出工作项类型定义文件。有关更多信息，请参见 witexport。

  • 使用 witfields 命令行实用工具重命名或删除 Team Foundation Server 上有冲突的字段。但是，应知道重命名和删除现有工作项字段并非总是可行。有关更多信息，请参见 witfields。

“分析报告”或“迁移报告”中的各个部分未展开

在 Internet Explorer 的默认安全设置下，分析报告或迁移报告中的各个部分未正确展开。展开和折叠按钮是由脚本控制的，Internet Explorer 的默认安全性阻止这些脚本运行。

解决方案

将 Internet Explorer 安全性更改为允许报告中的活动内容执行即可纠正此问题。

更改安全性以允许报告上的活动内容

  1. 找到靠近浏览器顶部的黄色安全栏，其显示“为帮助保护您的安全，Internet Explorer 已经限制此文件显示可能访问您的计算机的活动内容”。

  2. 单击黄色安全栏，然后单击“允许阻止的内容”。

  3. 在“安全警告”对话框中单击“是”。

工作项架构更改未迁移到 Team Foundation Server

如果已提供工作项类型，则不会应用工作项架构更改。这通常在以下情况下发生：您运行了一次 Migrate 命令，修改了架构映射文件中的工作项类型定义，然后再次运行 Migrate 命令。这些修改不会出现在 Team Foundation Server 中。而且，迁移报告中显示以下警告：“无法创建工作项类型 <类型名称>，因为该类型在 Team Foundation Server 中已存在。”

转换器会进行显式检查，以确保它未覆盖现有工作项类型。因此，只要工作项类型是由转换器提供的，即使您修改了工作项类型，更改也不会被并入，因为工作项类型已经提供。

解决方案

若要更新 Team Foundation 服务器上的工作项类型，请使用 witimport 命令行实用工具将工作项类型导入 Team Foundation Server。然后，转换器将在您迁移工作项时使用更新的类型。使用 witimport 命令行实用工具时，请注意不要修改或删除工作项数据。有关更多信息，请参见 witimport。

附件上载失败导致工作项迁移失败

如果附件大于允许的附件大小，则这些附件不会迁移。同时，下面的错误将在迁移报告文件中列出；“TF61015: 为工作项 <id> 保存附件‘<文件名>’失败，出现以下错误: 正在上载的文件大于所允许的最大上载文件大小(4MB)。”

解决方案

  • 可增加 Team Foundation 服务器上附件的最大大小以修正此问题。默认大小为 4 MB，但是可将该大小增加到 2 GB（2147483648 字节）。

设置工作项的附件大小最大值

  1. 在 Internet Explorer 中定位到下面的 URL：

    http://<TFS 服务器>:8080/WorkItemTracking/v1.0/ConfigurationSettingsService.asmx?op=SetMaxAttachmentSize

    其中“<TFS 服务器>”表示 Team Foundation 服务器的名称。

  2. 在“maxSize”框中，输入附件大小最大值（以字节为单位），然后单击“调用”。附件大小最大值为 2 GB。

说明：

若要执行此过程，您必须是 Team Foundation 应用层服务器上“Administrators”组的成员，还必须是“Team Foundation Administrators”组的成员。有关更多信息，请参见 Team Foundation Server 权限。

请参见

概念

Team Foundation Server 权限

其他资源

工作项迁移疑难解答