解决迁移错误

项目
05/21/2024

在迁移到 Azure DevOps Services 之前，数据迁移工具会标记需要更正的错误。本文介绍在准备迁移时可能收到的最常见警告和错误。更正每个错误后，再次运行 迁移程序验证 命令以验证解决方法。

消除大小警告

运行数据迁移工具后，超大型集合可能会生成以下消息之一。如果收到上述任何警告或错误，建议尝试减小数据库的大小。

数据库大小超过建议大小

以下警告意味着需要使用 SQL Azure VM 方法来完成迁移。数据库达到特定大小后，设置 SQL Azure VM 以完成迁移到 Azure DevOps Services 的速度会更快。若要设置 VM 并完成迁移，请按照警告消息链接的说明进行操作。

The database is currently {Database Size}GBs. This is above the recommended size of {DACPAC Size Limit}GBs to use the DACPAC migration method. Please see the following page to learn how to migration using a SQL Azure VM: https://aka.ms/AzureDevOpsImportLargeCollection

此警告 并不意味着 集合太大，无法迁移。

超出建议大小的表大小

与前面的警告类似，以下警告意味着必须使用 SQL Azure 虚拟机（VM）方法来完成迁移。若要设置 VM 并完成迁移，请按照警告消息链接的说明进行操作。

The largest table size is currently {Table size}GBs. This is above the recommended size of {Size limit}GBs to use the DACPAC migration method. Please see the following page to learn how to migration using a SQL Azure VM: https://aka.ms/AzureDevOpsImportLargeCollection

此警告 并不意味着 集合太大，无法迁移。

数据库元数据大小超过建议的大小

以下警告表示数据库即将达到元数据总大小限制。元数据大小是指数据库的大小，而不包括文件、代码和其他二进制数据。建议在迁移之前减小数据库的大小。减小大小可提供加快迁移速度的另一个好处。

The database metadata size is currently {Metadata Size}GBs. This is above the recommended size of {Warning Size}GBs. It's recommended that you consider cleaning up older data as described in [Cleaning up old data](/azure/devops/server/upgrade/clean-up-data).

警告 并不意味着 集合太大，无法迁移，而是其元数据大小大于大多数其他数据库。

数据库元数据大小超过支持的最大大小

与前面的警告不同，以下错误将阻止你继续迁移。

它指示集合中的元数据量太大。若要继续迁移，需要减小超出指示的限制的大小。

The database metadata size is currently {Metadata Size}GBs. This is above the maximum supported size of {Metadata Limit}GBs.

消除排序规则警告

排序规则警告是指集合数据库的排序规则。排序规则控制字符串值的排序和比较方式。未使用或SQL_Latin1_General_CP1_CI_ASLatin1_General_CI_AS接收其中一条警告消息的集合。

无本机支持

收到以下警告意味着在执行迁移之前，需要考虑排序规则的含义。

The collection database's collation '{collation}' is not natively supported in Azure DevOps Services. Importing your collection will result in your collation being converted to one of the supported Azure DevOps Services collations. See more details at https://aka.ms/AzureDevOpsImportCollations

此警告 并不意味着 无法迁移集合。

此警告要求你确认接受警告。接受警告后，数据迁移工具可以继续迁移准备。

将不受支持的排序规则迁移到 Azure DevOps Services 时，排序规则将转换为受支持的排序规则。虽然此转换通常没有问题，但迁移或迁移失败后可能会出现意外结果。

例如，客户可能会注意到包含非英语字符的字符串的不同顺序。迁移后，非英语字符（如“é”）可能等效于英语“e”。在迁移具有不受支持的排序规则的集合时，请务必完成并验证测试运行迁移。

没有本机支持，没有 Internet 连接

如果数据迁移工具无法连接到 Internet，则无法验证排序规则的转换。这只是一条警告，因此可以继续迁移过程。但是，运行 prepare 命令时，需要 Internet 连接，此时会验证排序规则转换。

The collections database's collation '{collation}' is not natively supported in Azure DevOps Services. It could not be validated that the collation can be converted during migration to a supported Azure DevOps Services collation, as there was no internet connection. Please run the command again from a machine with an internet connection. See more details at https://aka.ms/AzureDevOpsImportCollations

不支持的数据库排序规则

通常，可以在迁移时将非支持排序规则转换为受支持的排序规则。但是，某些排序规则无法转换。如果集合使用这些排序规则之一，将收到以下 错误消息 。

The collection database's collation '{collation}' is not supported for migration to Azure DevOps Services. It will need to be changed to a supported collation before it can be imported. See more details at https://aka.ms/AzureDevOpsImportCollations

若要继续，需要将集合的排序规则更改为 Azure DevOps Services 上受支持的排序规则之一。

更正标识错误

修复迁移前的标识错误，以防止出现问题。旧 TFS 操作在新 Azure DevOps Server 上无效时很少发生。例如，某些用户不再位于有效的用户组中。

以下部分提供了解决最常见的标识错误的指南。

ISVError：100014

此错误表示系统安全组中缺少权限。例如，你创建的每个集合都有 Project Collection Valid Users 和 Project Collection 管理员istrators 组。系统默认创建它们。这些组不支持编辑其权限。

此错误指示一个或多个组缺少它应具有的权限。若要解决此错误，请使用 TFSSecurity.exe 命令将预期权限应用于已标记的系统组。第一步是确定需要运行的 TFSSecurity 命令。

项目集合有效用户错误消息

检查一个或多个错误消息，其中突出显示了数据迁移工具。如果标记的组以“0-0-0-0-3”结尾，如以下示例中所示，则需要修复项目集合有效用户组缺少的权限。

运行以下命令，将范围替换为错误消息中的作用域并指定集合 URL。

TFSSecurity.exe /a+ Identity "{scope}\\" Read sid:{Group SID} ALLOW /collection:{collectionUrl}

从错误消息中确定范围和组安全 ID（SID）。

ISVError:100014 Missing permission for group:Microsoft.TeamFoundation.Identity;S-1-9-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-0-0-0-0-3 for scope:397c326b-b97c-4510-8271-75aac13de7a9. Expected:1 and Actual:0

最后一个命令如下所示：

TFSSecurity.exe /a+ Identity "397c326b-b97c-4510-8271-75aac13de7a9\\" Read sid:S-1-9-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-0-0-0-0-3 ALLOW /collection:https://localhost:8080/defaultcollection

Project Collection 管理员istrators 错误消息

仔细检查突出显示的数据迁移工具的错误消息。如果标记的组以“0-0-0-0-0-1”结尾，如以下示例中所示，则需要修复 Project Collection 管理员istrators 组缺少的权限。针对 TFSSecurity.exe运行以下命令，将范围替换为错误消息中的作用域并指定集合。

TFSSecurity.exe /a+ Identity "{scope}\\" Read sid:{Group SID} ALLOW /collection:{collectionUrl}

TFSSecurity.exe /a+ Identity "{scope}\\" Write sid:{Group SID} ALLOW /collection:{collectionUrl}

TFSSecurity.exe /a+ Identity "{scope}\\" Delete sid:{Group SID} ALLOW /collection:{collectionUrl}

TFSSecurity.exe /a+ Identity "{scope}\\" ManageMembership sid:{Group SID} ALLOW /collection:{collectionUrl}

在以下示例中，从错误消息中获取范围和组 SID ，并将其添加到前面的命令。

ISVError:100014 Missing permission for group:Microsoft.TeamFoundation.Identity;S-1-9-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-0-0-0-0-1 for scope:0c7c2216-fa4b-4107-a203-82b324a147ef. Expected:15 and Actual:0

最后一个命令如下所示：

TFSSecurity.exe /a+ Identity "0c7c2216-fa4b-4107-a203-82b324a147ef\\" Read sid:S-1-9-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-0-0-0-0-1 ALLOW /collection:https://localhost:8080/defaultcollection

TFSSecurity.exe /a+ Identity "0c7c2216-fa4b-4107-a203-82b324a147ef\\" Write sid:S-1-9-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-0-0-0-0-1 ALLOW /collection:https://localhost:8080/defaultcollection

TFSSecurity.exe /a+ Identity "0c7c2216-fa4b-4107-a203-82b324a147ef\\" Delete sid:S-1-9-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-0-0-0-0-1 ALLOW /collection:https://localhost:8080/defaultcollection

TFSSecurity.exe /a+ Identity "0c7c2216-fa4b-4107-a203-82b324a147ef\\" ManageMembership sid:S-1-9-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-XXXXXXXXXX-0-0-0-0-1 ALLOW /collection:https://localhost:8080/defaultcollection

需要更正多个错误时，建议创建批处理文件以自动执行命令。执行命令后，重新运行数据迁移验证工具以验证解决方法。如果某些错误仍然存在，请联系 Azure DevOps Services 客户支持。

ISVError：300005

ISVError：300005指示非组标识是每个人组的成员，更通常称为“有效用户组”。有效用户组是为所有项目和集合定义的默认组。这些组不可编辑。它们旨在仅包含其他 Azure DevOps 权限或安全组作为成员。此错误表示 Active Directory （AD）组或用户标识在有效用户组中具有直接成员身份。

重要

在运行以下命令解决此错误之前，请确保已备份集合和配置数据库。

由于无法直接编辑有效用户组，因此需要针对配置数据库运行 SQL 语句来删除有问题的标识并更正无效的成员身份。仔细检查数据迁移工具突出显示的错误消息。复制，GroupSidMemberId并ScopeId根据需要将这些值放入以下命令中。

DECLARE @p6 dbo.typ_GroupMembershipTable

INSERT into @p6 values('{GroupSid}','Microsoft.TeamFoundation.Identity','{MemberId}',0)
 
EXEC prc_UpdateGroupMembership @partitionId=1,@scopeId='{ScopeId}',@idempotent=1,@incremental=1,@insertInactiveUpdates=0,@updates=@p6,@eventAuthor='9EE20697-5343-43FC-8FC5-3D5D455D21C5',@updateGroupAudit=0

以下示例列出了 ISVError 的示例：从数据迁移工具300005消息。

ISVError:300005 Unexpected non group identity was found to have direct membership to everyone group. GroupSid:S-1-9-1551374245-3746625149-2333054533-2458719197-2313548623-0-0-0-0-3, MemberId:76050ddf-4fd8-48c4-a1ff-859e44364519, ScopeId:7df650df-0f8b-4596-928d-13dd89e5f34f

如果错误消息列出了一个 MemberSid，则需要从配置数据库中的dbo.tbl_Identity表中获取 MemberID 该表。然后，可以使用该 MemberIDID 查找 GUID MemberSid。

ISVError:300005 Unexpected non group identity was found to have direct membership to everyone group. GroupSid:S-1-9-1551374245-3746625149-2333054533-2458719197-2313548623-0-0-0-0-3, MemberSid:System.Security.Principal.WindowsIdentity;S-1-5-21-124525095-708259637-1543119021-1737349, ScopeId:7df650df-0f8b-4596-928d-13dd89e5f34f

DECLARE @MemberId uniqueidentifier 

SET @MemberId = (Select Id from dbo.tbl_Identity where Sid ='S-1-5-21-124525095-708259637-1543119021-1737349');

SELECT @MemberId

复制 GroupSidSQL MemberId命令，并将其 ScopeId 复制到 SQL 命令中。


DECLARE @p6 dbo.typ_GroupMembershipTable

INSERT into @p6 values('S-1-9-1551374245-3746625149-2333054533-2458719197-2313548623-0-0-0-0-3','Microsoft.TeamFoundation.Identity','76050ddf-4fd8-48c4-a1ff-859e44364519',0)
 
EXEC prc_UpdateGroupMembership @partitionId=1,@scopeId='7df650df-0f8b-4596-928d-13dd89e5f34f',@idempotent=1,@incremental=1,@insertInactiveUpdates=0,@updates=@p6,@eventAuthor='9EE20697-5343-43FC-8FC5-3D5D455D21C5'

针对 Azure DevOps Server 配置数据库运行已完成的命令。对每个 ISVError 重复此命令：报告300005实例。可以将具有相同范围 ID 的错误批处理到单个命令中。执行命令后，重新运行数据迁移工具将再次验证以确保更正错误。如果错误仍然存在，请联系 Azure DevOps Services 客户支持。

重要

若要解决这些错误，必须附加集合。

如果在运行命令时收到 -1 结果，请确保生成错误的集合数据库附加到 Azure DevOps Server 实例，并在配置数据库上运行该命令。

Microsoft Entra 超时异常

在极少数情况下，运行数据迁移工具准备命令时，可能会收到 Microsoft Entra 超时错误。

Exception Message: Request failed (type AadGraphTimeoutException)

此错误表示向 Microsoft Entra ID 发出的请求，以查找集合中用户的匹配 Microsoft Entra 标识超时。通常，可以通过等待在一天不太繁忙的时间运行准备命令（例如在常规工作时间之后）来解决此错误。

若要进行故障排除，请从准备计算机测试 Microsoft Entra ID 连接。按照以下步骤从 Microsoft Entra ID 获取用户信息。

在提升模式下打开 PowerShell，并将以下命令中的“”someone@somecompany.com替换为 Microsoft Entra 用户标识。

# Install the Microsoft Graph PowerShell module - ensuring to select Yes to All
Install-Module Microsoft.Graph 

# Import Users module
Import-Module Microsoft.Graph.Users

# Connect to Microsoft Entra and use your Microsoft Entra ID credentials (someone@somecompany.com) to login when the pop-up appears
Connect-MgGraph  -Scopes 'User.Read.All'

# Try to retrieve information on a user from your Microsoft Entra
Get-MgUser -Filter "UserPrincipalName eq 'someone@somecompany.com'"

如果步骤失败或找不到用户，检查准备计算机与 Microsoft Entra ID 之间的连接。运行网络跟踪，准备查看网络是否阻止调用。否则，请联系Azure 支持。检查日志文件中是否有用户信息。

Number of active users is {Number of Users}.

如果活动用户数超过 50,000，则映射的标识量可能需要超过超时限制提供的时间。检查集合中是否包含大型组，例如“每个人”组。如果可能，请删除这些组，然后重试。如果仍无法解决此错误，请联系 Azure DevOps Services 客户支持。

更正进程错误

有关解决常见进程错误的详细信息，请参阅“验证”阶段文章“解决进程模板。

更正字段验证错误

VS403310

检测到集合文件中不一致时，可能会出现以下错误消息。如果遇到此错误，请联系客户支持。

VS403310: An inconsistency was detected in some of the files in the collection.

VS403442

本地集合和 Azure DevOps Services 系统字段之间有时会发生字段名称冲突。

In order to migrate successfully, you must rename field *{TFSfieldReferenceName}*. Given name *{TFSfieldName}* is reserved for field *{VSTSfieldReferenceName}*.

若要解决此错误，请更改集合字段的名称。 从 witadmin 使用 witadmin changefield 命令。

witadmin changefield /collection:http://AdventureWorksServer:8080/DefaultCollection /n:TFSfieldReferenceName /name:newFieldName

VS403443

以下错误指示本地集合与特定 Azure DevOps Services 字段之间存在字段名称冲突。

In order to migrate successfully, you must rename field *{TFSfieldReferenceName}* to *{VSTSfieldName}*. Given name for *{TFSfieldReferenceName}* is *{TFSfieldName}*

若要解决此错误，请使用 witadmin changefield 命令。有关详细信息，请参阅 witadmin。

witadmin changefield /collection:http://AdventureWorksServer:8080/DefaultCollection /n:TFSfieldReferenceName /name:VSTSfieldName

VS403444

以下错误指示本地集合与 Azure DevOps Services 之间存在字段类型冲突。

使用 witadmin，只能更改 HTML 或 PlainText 字段的数据类型。

In order to migrate successfully, you must set type of field *{TFSfieldReferenceName}* to *{Type}*. Given type for *{TFSfieldReferenceName}* is *{collectionType}*.

如果字段类型为 HTML 或 PlainText，则可以将其类型更改为所需类型。

witadmin changefield /collection:http://AdventureWorksServer:8080/DefaultCollection /n:TFSfieldReferenceName  /type:PlainText | HTML

注意

如果字段类型与 HTML 或 PlainText 不同，并且字段数据不重要，或者字段未在任何项目中使用，则建议删除该字段。

witadmin deletefield /collection:http://AdventureWorksServer:8080/DefaultCollection /n:TFSfieldReferenceName

重要

删除字段会导致整个集合中的字段数据丢失。

解决验证失败问题

验证失败意味着迁移未启动。数据迁移工具尝试对迁移进行排队，但出现错误。迁移请求无效。修复错误消息，然后再次尝试迁移。

VS403254

不支持为 Azure DevOps Services 迁移输入的区域。

VS403254: Region {0} might not be used for the Import, it is not a supported region.

打开迁移规范文件并更新你为该区域提供的正确短名称的区域。

VS403249

所选团队的组织名称已被现有组织使用。所有 Azure DevOps Services 迁移都会进入在迁移时创建的新组织。

VS403249: The organization {0} already exists. Please select a different name and try the migration again.

选择其他组织名称，并在重试迁移之前更新迁移规范文件。

VS403250 & VS403286

DACPAC 不是基于分离的集合生成的。

VS403250: The dacpac is not a detached Azure DevOps Server Collection database.

VS403286: The dacpac is from a Azure DevOps Server Configuration database. You must use a detached Azure DevOps Server Collection database.

分离集合数据库并再次生成 DACPAC。

VS403243

无法使用提供的 SQL 连接ion String 与数据库建立连接。

VS403243: Unable to connect to the database using the provided SQL Connection String {0}.

查看提供的参数以确保它们正确无误，然后重试。

VS403260 & VS403351

未分离集合数据库。

VS403260: The database is not detached.

VS403351: The DACPAC or source database is missing an expected table. It's possible that the database was not correctly detached from Azure DevOps Server.

分离集合数据库并重试迁移队列。

VS403261

连接字符串必须加密，否则密码会以明文形式发送。

VS403261: The SQL connection string must use encryption.

将 Encrypt=true 添加到 SQL 连接字符串。

VS403262

连接字符串必须使用 SQL 身份验证。

VS403262: The SQL connection string must use SQL Authentication, Integrated Authentication is not supported.

将集成安全性=False 添加到 SQL 连接字符串。

VS403263

SQL 登录用户帐户没有所需的数据库角色。

VS403263: The User ID {0} must be member of the database role {1}.

确保为登录的用户帐户分配了“TF标准版XECROLE”角色。

注意

使用 sp_addrolemember 添加到 TFSEXECROLE 现有 SQL 登录名时存在已知问题。在关闭使用该标识的所有打开连接之前，不会应用角色成员身份。如果收到VS403263错误并已确认你的标识具有该角色，我们建议你为迁移创建新的标识。

VS403264

连接字符串不指向 Azure DevOps Server 集合数据库。

VS403264: The database is not a Azure DevOps Server Collection database, it cannot be used for migration.

验证或更正连接字符串指向集合数据库。

VS40325

Azure DevOps Server 更新已将文件迁移作业排队。在完成此作业之前，无法执行迁移。此作业的完成时间取决于集合的大小。

VS403255: The collection cannot be imported due to an ongoing post upgrade job. Please wait and try again later

可以通过对集合数据库运行以下查询来跟踪作业进度：

SELECT  COUNT (*) as remaining_files_to_migrate
FROM    tbl_FileReference
WHERE   PartitionId > 0
        AND MigrateFileId IS NOT NULL

迁移剩余的文件数为零后，可以运行数据迁移工具。

VS403282

源位置值中存在新的行字符。从 Windows 控制台复制 SAS 密钥后，此字符可能保持不变。

VS403282: The source location parameter contains a new line character. Please ensure the SAS key is defined on a single line in the migration specification file.

删除换行符，然后重试。

VS403271

迁移文件和 DACPAC 不在 所需的 Azure 区域中，无法完成到目标 Azure DevOps Services 区域的迁移。

VS403271: It appears that your DACPAC was uploaded to East US. It's required that customers targeting Central US for migration put their DACPACs in Central US. Please move your DACPAC to Central US and requeue the migration.

在所需区域中创建新的 Microsoft Azure 存储帐户并复制文件。以下示例演示如何使用 AzCopy 复制数据。

AzCopy.exe /Source:https://accountSCUS.blob.core.windows.net/mycontainer /SourceKey:"primary access key" /Dest:https://accountCUS.blob.core.windows.net/mycontainer /DestKey:"primary access key" /S

VS403316

集合中的某些 Team Foundation 版本控制（TFVC）文件中检测到不一致。

VS403316: An inconsistency was detected in some TFVC files for this collection. The inconsistency needs to be corrected prior to running a migration to Azure DevOps Services. Please reach out to https://aka.ms/AzureDevOpsImportSupport for assistance with addressing this issue.

使用 Azure DevOps Services 客户支持。打开支持票证，并与你合作解决错误。

VS403366

数据迁移工具无法连接到 SQL Azure VM。

VS403366: A problem occurred while attempting to connect to your database. Please verify that your connection string is correct and that all required IP addresses for Azure DevOps Services have been provided exceptions for your machines firewall.

List of Azure DevOps Services IPs:

验证是否已在连接字符串中正确输入信息，以及是否可以连接到 VM。

错误消息列表的 IP 适用于 Azure DevOps Services。 Azure DevOps Services IP 可以在部署期间暂时更改。将它们添加到防火墙例外，然后再次尝试排队迁移。有关 IP 地址的列表，请参阅 “迁移大型集合”，仅限制对 Azure DevOps Services IP 的访问。

VS403373

数据迁移工具不支持迁移 SAME 集合的多个副本。但是，它确实支持迁移集合的拆分副本。更改 DataImportCollectionID 的 GUID。

在 SQL Server Management Studio（SSMS）中，打开尚未迁移的拆分副本的扩展属性。将新生成的 GUID 添加到“TFS_DATAIMPORT_COLLECTIONID”属性。然后重新运行 prepare 命令，并使用新的 migration.json 文件对迁移进行排队。

VS403379

数据迁移失败，因为在此集合中找到的一个或多个项目处于软删除阶段。在运行数据迁移之前，还原软删除的项目或删除它们。有关详细信息，请参阅 “删除项目”。

VS403379: Data migration will fail as one or more projects found in this collection are in the soft-deleted stage. Please restore the soft-deleted project(s) or delete them permanently before running the data migration.

验证运行数据迁移工具的集合是否具有软删除阶段的项目。删除项目后，它将保持软删除状态 28 天，在此期间可以还原已删除的项目。可以了解如何在还原项目中还原已删除的项目。如果项目位于软删除阶段，请在运行数据迁移之前将其完全删除或还原回。

解决迁移失败

迁移失败意味着迁移已排队，但未完成。排队迁移的人员会收到失败的电子邮件通知。大多数时候，此电子邮件包括失败的原因。如果确实如此，请使用电子邮件和此页面中提供的故障排除步骤来解决错误，然后重试迁移。

如果错误更为复杂，则收到的电子邮件提供有关如何提交客户支持案例的说明。提交客户支持案例后，团队必须通过使 Azure DevOps Server 实例重新联机并重新附加集合来回滚。然后，贵团队成员即可继续工作。建议不要再次尝试迁移，直到导致问题解决的失败为止。

通过