Validar e resolver erros relacionados a modelos de processo

  • Artigo

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

Como parte do processo de importação de migração, a ferramenta de migração de dados verifica o processo usado pelos projetos na coleção. Corrija todos os erros que forem sinalizados.

Depois de resolver os erros, execute novamente o comando da ferramenta de migração de validate dados para verificar se todos os erros foram corrigidos.

Observação

É recomendável usar o Guia de Migração para avançar na importação. O guia vincula-se à documentação técnica conforme necessário.

Com o lançamento do Azure DevOps Server 2019, o Serviço de Importação de Banco de Dados do TFS foi renomeado para Migrar para o Azure DevOps. Isso inclui tfsMigrator se tornando a ferramenta de migração de dados ou migrador para abreviar. Esse serviço ainda funciona exatamente da mesma forma que o antigo Serviço de Importação. Se você estiver em uma versão mais antiga do local com o TFS como a identidade visual, ainda poderá usar esse recurso para migrar para o Azure DevOps, desde que você atualize para uma das versões com suporte.

Tipos de validação de processo

Durante a validação, a ferramenta de migração de dados determina o modelo de processo de destino para cada projeto. Ele atribui automaticamente um dos dois modelos de processo a seguir a cada projeto na coleção:

  • Modelo de processo herdado: se o projeto foi criado com o modelo de processo Agile, Scrum ou CMMI e nunca foi personalizado.
  • Modelo de processo XML hospedado: se o processo do projeto parecer ter sido personalizado. Um processo personalizado contém campos personalizados, tipos de item de trabalho ou outros tipos de personalizações.

Quando o processo XML hospedado é o modelo de processo de destino, a ferramenta de migração de dados valida se as personalizações podem ser migradas. A ferramenta de migração de dados gera dois arquivos durante a validação:

  • DataMigrationTool.log: Contém o conjunto de erros de validação de processo encontrados na coleção. Corrija todos os erros de processo encontrados para prosseguir com a migração.

  • TryMatchOobProcesses.log: Lista para cada projeto o modelo de processo de destino - Herança ou XML hospedado. Para projetos definidos para o modelo de processo XML hospedado, ele explica por que eles são considerados personalizados. Você não precisa corrigir esses erros, mas eles fornecem orientação sobre o que fazer caso você queira migrar para o modelo de processo de herança. Observe que, depois que uma coleção é importada, você pode migrar um projeto para um modelo de processo de herança.

A maioria dos clientes tem uma mistura de projetos dentro de uma coleção. Alguns projetos usam um modelo de processo padrão e outros usam modelos de processo personalizados. A ferramenta de migração de dados verifica e valida cada projeto de acordo. É muito possível que você tenha uma mistura de projetos, alguns mapeados para um processo herdado e outros para um processo XML hospedado.

Recomendamos que, para qualquer projeto que não tenha sido personalizado, você revise o TryMatchOobProcesses.log para determinar se há erros. Em caso afirmativo, faça os ajustes de acordo para que o projeto possa ser mapeado para um processo herdado após a importação de dados.

Atualização para um processo do sistema

Se você começou com uma versão mais antiga do Servidor de DevOps do Azure, é provável que seus projetos ainda estejam usando um modelo de processo mais antigo. Se esses projetos não tiverem sido atualizados usando o Assistente para Configurar Recursos , a ferramenta de migração de dados localizará erros de processo. Em alguns casos raros, se o processo for muito antigo, mesmo o Assistente para Configurar Recursos não conseguirá resolver os erros.

Aqui estão alguns exemplos de mensagens de erro que você pode receber:

Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402571: Required element PortfolioBacklog is missing from Process Configuration.
Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402571: Required element BugWorkItems is missing from Process Configuration.
Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402571: Required element FeedbackRequestWorkItems is missing from Process Configuration.
Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402571: Required element FeedbackResponseWorkItems is missing from Process Configuration.
Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402574: ProcessConfiguration doesn't specify required TypeField Team.
Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402574: ProcessConfiguration doesn't specify required TypeField RemainingWork.
Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402574: ProcessConfiguration doesn't specify required TypeField Order.
Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402574: ProcessConfiguration doesn't specify required TypeField Effort.
Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402574: ProcessConfiguration doesn't specify required TypeField Activity.
Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402574: ProcessConfiguration doesn't specify required TypeField ApplicationStartInformation.
Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402574: ProcessConfiguration doesn't specify required TypeField ApplicationLaunchInstructions.
Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF402574: ProcessConfiguration doesn't specify required TypeField ApplicationType.
Invalid process template: WorkItem Tracking\Process\ProcessConfiguration.xml:: TF400572: The Project Process Settings must be configured for this feature to be used.

Se você nunca personalizou seu projeto (campos adicionados, tipos de item de trabalho, etc.), corrigir esses erros é realmente muito simples. Se você personalizou seu processo, essa abordagem não funcionará. Você precisará alterar manualmente os modelos de processo para que suas personalizações não sejam substituídas.

Primeiro, certifique-se de saber como foi iniciado o processo do seu projeto. É Scrum, Agile ou CMMI? Neste exemplo, vamos supor Agile. Em seguida, vá para os Scripts de personalização de processo fornecidos no GitHub e baixe o repositório. Neste caso, vamos nos concentrar no conteúdo na pasta Importar .

Use o script ConformProject.ps1 para conformar um projeto de sua escolha ao processo do sistema Agile. Isso atualizará todo o projeto para ser Agile.

.\ConformProject.ps1 "<collection url>" "<project name>" "c:\process-customization-scripts\import\agile"

Certifique-se de fazer isso para cada projeto.

Resolver erros de processo

Seus modelos de processo são personalizados? Você está usando um modelo de processo desatualizado mais antigo? Nesse caso, você provavelmente terá erros de validação de processo. A ferramenta de migração de dados faz uma verificação exaustiva em relação aos modelos de processo. Ele verifica se é válido para os Serviços de DevOps do Azure. As chances são de que você precisará fazer alguns ajustes e aplicá-los à sua coleção.

Observação

Se você estiver usando um processo OOB Agile, Scrum ou CMMI, provavelmente não verá nenhum erro no DataMigrationTool.log. Em vez disso, verifique se há erros no TryMatchOobProcesses.log . Se você estiver livre de erros, seu projeto será mapeado para um processo OOB.

Há várias personalizações que não funcionarão nos Serviços de DevOps do Azure. Certifique-se de revisar a lista de personalizações com suporte.

Se você tiver projetos que estão usando um modelo de processo mais antigo, a ferramenta de migração de dados encontrará vários erros. Isso ocorre porque seus modelos de processo não foram atualizados para corresponder aos modelos de processo mais recentes. Para começar, tente executar o Assistente para Configurar Recursos para cada projeto. Isso tentará atualizar seus modelos de processo com os recursos mais recentes. Isso deve reduzir drasticamente a contagem de erros.

Finalmente, certifique-se de ter witadmin na máquina que você pretende usar para corrigir os erros de processo. Esta pode ser a sua área de trabalho local. A witadmin ferramenta de linha de comando é usada nos scripts automatizados e é necessária sempre que faz alterações nos modelos de processo.

Etapa 1 - Revisar erros

DataMigrationTool.log arquivo será gerado e contém a lista de erros que o processo de validação encontrou. Para exibir os logs, abra DataMigrationTool.log arquivo. Procure a string "Validação - Iniciando a validação do projeto 1". Cada projeto é validado. Examine todos os projetos e procure por quaisquer linhas que contenham um prefixo de [Error ....

Arquivo de log de processo gerado pela ferramenta de migração de dados

Para obter uma lista de erros de validação, consulte Resolver erros de validação para importação de processo. Para cada erro de validação, fornecemos o número do erro, a descrição e o método a ser resolvido.

Passo 2 - Corrigir erros

Depois de determinar quais projetos têm erros e os detalhes do erro, corrija os erros. A correção dos erros requer que você altere a sintaxe XML e aplique as alterações de volta ao projeto.

Observação

Recomendamos que você não use o TFS Power Tools para fazer esse trabalho. Em vez disso, é altamente recomendável que você modifique o XML manualmente.

Para obter o modelo de processo do projeto, adicione o parâmetro /SaveProcesses ao executar o comando da ferramenta de migração de dados.

Migrator validate /collection:{collection URL} /tenantDomainName:{name} /region:{region} /SaveProcesses

Esse comando extrairá o XML do projeto e o colocará na mesma pasta que os logs. Extraia os arquivos zip para sua máquina local para que você possa editar os arquivos.

Agora, corrija o XML. Use os DataMigrationTool.log logs do arquivo para determinar os erros para cada projeto.

Arquivo de log de processo gerado pela ferramenta de migração de dados

Alguns erros exigirão que você use um witadmin changefield comando. Alterar um nome de campo é o exemplo mais comum. Para economizar algum tempo, recomendamos que você execute o witadmin changefield comando e, em seguida, execute novamente a ferramenta de migração de dados. Isso reexportará o XML com os nomes corrigidos. Caso contrário, você também precisará corrigir manualmente os campos na sintaxe XML.

Depois de fazer uma correção, aplique as alterações de volta ao Servidor de DevOps do Azure. Para fazer isso, dependendo das alterações feitas, você precisará executar um ou mais witadmin comandos. Para tornar isso mais fácil para você, criamos um script do PowerShell para automatizar o processo. O script contém todos os witadmin comandos necessários para conformar todo o processo.

Você pode obter os scripts em Process Customization Scripts. Use o script import/ConformProject.ps1 .

.\conformproject.ps1 "<collection url>" "<project name>" "<process template folder>"

Script de processos de projeto em conformidade em execução

Quando o script for concluído, execute novamente a ferramenta de migração de dados para validar a coleção. Siga as etapas 1 a 3 até que a ferramenta de migração de dados não gere mais erros de validação.

Dica

Se você é novo em XML e witadmin, sugerimos que você faça uma correção de cada vez e, em seguida, em conformidade. Continue esse loop até que todos os erros sejam resolvidos.

Erros comuns de validação

VS402841: Campo X no tipo de item de trabalho Bug tem syncnamechanges=false, mas tem regras que o tornam um campo de identidade. Os campos de identidade devem ter syncnamechanges=true. Atualize seu modelo de processo para incluir essa alteração.

Nos Serviços de DevOps do Azure, adicionamos uma regra para que cada campo de identidade tenha o atributo syncnamechanges=true . No Servidor de DevOps do Azure, essa regra não se aplica. Portanto, a ferramenta de migração de dados identificará isso como um problema. Não se preocupe, fazer essa alteração no Servidor de DevOps do Azure local não causará nenhum dano.

Execute o comando witadmin changefield. A sintaxe do comando é semelhante à seguinte:

witadmin changefield /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:fieldname /syncnamechanges:true

Para obter mais informações sobre o comando, consulte Gerenciar campos de witadmin changefield item de trabalho.

TF402556: Para que o campo System.IterationId seja bem definido, você deve nomeá-lo Iteration ID e definir seu tipo como Integer.

Esse erro é típico de modelos de processo antigos. Tente executar o Assistente para Configurar Recursos em cada projeto. Como alternativa, você pode executar o seguinte witadmin comando:

witadmin changefield /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:fieldname /name:newname

TF402571: O elemento necessário BugWorkItems está ausente da Configuração do processo.

Esse erro geralmente ocorre quando um processo não é atualizado há algum tempo. Tente executar o assistente de configuração de recursos em cada projeto a ser resolvido.

TF402564: Você definiu XX listas globais. Apenas 64 são permitidos.

Por padrão, os Serviços de DevOps do Azure darão suporte a 64 listas globais. Normalmente, você encontrará esse erro se tiver uma grande quantidade de pipelines de compilação. A lista global chamada Builds - TeamProjectName é criada para cada novo pipeline de compilação. Você precisará remover as listas globais desatualizadas.