Gerenciar campos de item de trabalho

  • Artigo

Serviços de DevOps do Azure | Azure DevOps Server 2022 - Azure DevOps Server 2019

Importante

Para o modelo de processo XML local, você pode usar witadmin para listar, importar, exportar e modificar um processo para um projeto. Para os modelos de processo XML herdado e hospedado, você só pode usar witadmin para listar e exportar informações do processo. Para obter uma visão geral dos modelos de processo e do que é suportado, consulte Personalizar sua experiência de acompanhamento de trabalho.

Você pode gerenciar os campos definidos para tipos de item de trabalho que são definidos para uma coleção de projetos (XML local) usando os seguintes comandos witadmin . Se quiser adicionar um campo global (válido para XML local), você pode fazê-lo modificando o arquivo de fluxo de trabalho global e importando-o para a coleção.

  • changefield: Altera um ou mais atributos de um campo. Ao alterar um dos seguintes atributos, você o altera para todos os tipos de item de trabalho e projetos dentro da coleção de projetos:

    • Tipo de dados para PlainText ou HTML campos.

      Importante

      Quando você atualiza o Team Foundation Server de uma versão anterior para a versão atual, a atribuição de tipo para o campo Descrição (System.Description) é convertida automaticamente de PlainText para HTML. Com o changefield comando, você pode restaurar o conteúdo deste campo para exibir texto sem formatação.

    • Nome amigável que é exibido na consulta de item de trabalho. Esse nome pode ser diferente daquele exibido no formulário de item de trabalho.

    • Atributos de relatório que incluem o nome do campo como ele aparece em um relatório, o nome do relatório de referência e o tipo de relatório.

    • Sincronização com o Ative Directory - você pode ativar/desabilitar a sincronização de campos de nome de pessoa.

  • deletefield: Exclui o campo especificado.
  • listfields: Lista os atributos para todos os campos ou um campo especificado.

Nota

O witadmin indexfield comando foi preterido com o Azure DevOps Server 2019 e versões posteriores. Os campos de indexação não são mais necessários.

Executar a ferramenta de linha de witadmin comando

Para executar a ferramenta de linha de comando, abra uma janela de prompt de comando onde o witadmin Visual Studio está instalado. A witadmin ferramenta de linha de comando é instalada com qualquer versão do Visual Studio. Você pode acessar essa ferramenta instalando a versão gratuita do Visual Studio Community ou do Visual Studio Team Explorer.

Nota

Para se conectar aos Serviços de DevOps do Azure, recomendamos que você use a versão mais recente do Visual Studio ou da Comunidade do Visual Studio.

Nota

Para se conectar a um servidor local, recomendamos que você use a mesma versão ou posterior do Visual Studio como seu Servidor de DevOps do Azure. Por exemplo, se você se conectar ao Azure DevOps Server 2019, conecte-se ao seu projeto a partir de uma versão do Visual Studio 2019.

Para o Visual Studio 2022

%programfiles(x86)%\Microsoft Visual Studio\2022\Community\Common7\IDE\CommonExtensions\Microsoft\TeamFoundation\Team Explorer

Enterprise ou Professional no lugar de Community, dependendo da versão instalada.

Para o Visual Studio 2019

%programfiles(x86)%\Microsoft Visual Studio\2019\Community\Common7\IDE\CommonExtensions\Microsoft\TeamFoundation\Team Explorer

Enterprise ou Professional no lugar de Community, dependendo da versão instalada.

Para Visual Studio 2017

%programfiles(x86)%\Microsoft Visual Studio\2017\Enterprise\Common7\IDE\CommonExtensions\Microsoft\TeamFoundation\Team Explorer

Professional ou TeamExplorer no lugar de Enterprise, dependendo da versão instalada.

Numa edição de 32 bits do Windows, substitua %programfiles(x86)% por %programfiles%. Você pode instalar o Visual Studio Community (que fornece acesso ao Team Explorer) ou o Visual Studio Team Explorer 2017 gratuitamente.

Para obter uma visão geral dos campos definidos em um modelo de processo padrão, consulte Índice de campo de item de trabalho.

Gorjeta

Com o witadmin, você pode importar e exportar arquivos de definição. Outras ferramentas que você pode usar incluem o Editor de processos (requer que você tenha instalado uma versão do Visual Studio). Instale o editor de modelo de processo do Visual Studio Marketplace.

Pré-requisitos

  • Para listar campos, você deve ter sua permissão Exibir informações no nível do projeto para o projeto na coleção definida como Permitir.
  • Para excluir ou renomear campos ou alterar um atributo de um campo, você deve ser membro do grupo de segurança Administradores do Team Foundation ou do grupo de segurança Administradores de Coleção de Projetos.

Para obter mais informações, consulte Alterar permissões no nível da coleção do projeto.

Nota

Mesmo se você entrar com permissões administrativas, você deve abrir uma janela de prompt de comando elevada para executar essa função em um servidor que esteja executando o Windows Server 2008. Para abrir uma janela elevada do Prompt de Comando, escolha Iniciar, abra o menu de atalho do Prompt de Comando e escolha Executar como Administrador. Para obter mais informações, consulte o site da Microsoft: Controle de acesso de usuário.

Sintaxe

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

witadmin deletefield /collection:CollectionURL /n:RefName [/noprompt]  

witadmin listfields /collection:CollectionURL /n:RefName [/unused]

Parâmetros

Parâmetro Descrição
/collection:CollectionURL Especifica o URI da coleção de projetos. Por exemplo:

Formato local:http://ServerName:Port/VirtualDirectoryName/CollectionName
Se nenhum diretório virtual for usado, use o seguinte formato: http://ServerName:Port/CollectionName.
/n:RefName
/n:Name		 O nome de referência de um campo de tipo de item de trabalho.
/index Especifica para habilitar ou desabilitar a indexação para o campo especificado. Especifique ativado para habilitar a indexação e desativado para desabilitar a indexação.
/name:NewName Especifica o novo nome para o campo.
/syncnamechanges Especifica para usar o campo de item de trabalho para armazenar nomes e atualizar à medida que as alterações são feitas no Ative Directory ou em um grupo de trabalho. Esta opção é válida somente quando um campo com o tipo de dados String é especificado para o typename.

Especifique true para habilitar a sincronização para o campo de dados, especifique false para desabilitar a sincronização para o campo de dados.
/reportingname:ReportingName Especifica o nome do campo no data warehouse a ser usado para relatórios.
/reportingrefname:ReportingRefName Especifica o nome de referência do campo no data warehouse a ser usado para relatórios.
/reportingtype:Type Especifica como o campo é usado no depósito para relatórios. Os seguintes valores são válidos:

- dimension: Usado para os campos Inteiro, Cadeia de Caracteres ou Data/Hora.
- detail: Usado para os campos Inteiro, Duplo, Cadeia de caracteres ou Data/hora.
- measure: Usado para os campos Inteiro e Duplo. O tipo de agregação padrão é soma. Você pode especificar outro tipo de agregação usando o parâmetro de fórmula .
- none: Usado para desativar a reportabilidade no campo.

Para obter mais informações, consulte Sobre campos e atributos de item de trabalho.
/reportingformula:Formula Especifica a fórmula de agregação a ser usada quando o campo é relatado como um measurearquivo . A única fórmula suportada é sum.
/type:HTML | PlainText Especifica para converter o conteúdo do campo de PlainText para HTML ou de HTML para PlainText. Você pode especificar essa opção somente para campos cuja atribuição de tipo é PlainText ou HTML. Consulte a referência do elemento FIELD (Definition).
/unused Lista todos os campos que não são usados por nenhum projeto definido na coleção de projetos.
/noprompt Desativa o prompt de confirmação.
/? ou help Exibe ajuda sobre o comando na janela do prompt de comando.

Sincronizando nomes de pessoas com o Ative Directory

Você deve habilitar manualmente a sincronização de quaisquer campos de item de trabalho personalizados usados para atribuir nomes de pessoas que façam referência ao Ative Directory. Você deve habilitar a sincronização para cada campo para cada coleção de projeto que contém os campos personalizados.

Todos os campos de referência do sistema que mostram nomes de pessoas têm o atributo syncnamechanges definido como true. Esses campos incluem System.AuthorizedAs, System.AssignedTo, System.ChangedBy e System.CreatedBy. Sincronização ativada para cada campo de nome de pessoa definido em um dos modelos de processo padrão. Para obter mais informações, consulte Atribuições e campos de fluxo de trabalho.

Depois que a sincronização estiver habilitada, o campo não mostrará mais uma cadeia de caracteres estática. Em vez disso, o campo mostra o nome associado a uma conta de usuário. Quando você altera o nome de usuário no Ative Directory ou no Grupo de Trabalho, um campo com syncnamechanges definido como true mostra automaticamente o novo nome.

Quando você atribui o syncnamechanges atributo a um campo String, o campo sempre aceita nomes de usuário válidos. No entanto, o campo não permite nomes de grupo que são armazenados no Team Foundation Server ou no Ative Directory se qualquer uma das seguintes condições for true:

  • A VALIDUSER regra é especificada em todos os tipos de item de trabalho

  • A VALIDUSER regra é especificada para um tipo de item de trabalho

  • A ALLOWEDVALUES regra é especificada para um tipo de item de trabalho e essa regra tem um critério de filtro que exclui grupos

    Para obter mais informações, consulte Todos os elementos FIELD.

Atributos que você pode alterar para cada tipo de item de trabalho

Você altera os seguintes atributos ou valores definidos para um campo alterando a definição de tipo de item de trabalho na qual o campo aparece:

  • Nome exibido no formulário de item de trabalho. Consulte Elementos WebLayout e Control ou Referência de elemento XML de controle.
  • Texto de ajuda. Consulte Regras e avaliação de regras.
  • Valores ou itens permitidos em uma lista de opções ou menu suspenso. Consulte os elementos XML ALLOWEDVALUES, SUGGESTEDVALUES e PROHIBITEDVALUES.

Exemplos

A menos que especificado de outra forma, os seguintes valores se aplicam em cada exemplo:

  • URI para a coleção de projetos: http://AdventureWorksServer:8080/tfs/DefaultCollection
  • Nome do campo do item de trabalho: AdventureWorks.Field
  • Codificação padrão: UTF-8

Listar campos

Use witadmin listfields para ver o conjunto de campos em uso, para selecionar um para adicionar a um tipo de item de trabalho. Além disso, você pode listar as atribuições de atributo definidas para um campo específico e determinar quais campos são usados por quais projetos.

Exibir os atributos de um campo de item de trabalho

  • Digite o comando a seguir para listar os atributos definidos para um campo especificado, como Microsoft.VSTS.Common.Issue.

    witadmin listfields /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:Microsoft.VSTS.Common.Issue

    As informações de campo e atributo aparecem para o campo nomeado, conforme mostrado neste exemplo.

    Field: Microsoft.VSTS.Common.Issue  
Name: Issue  
Type: String  
Reportable As: dimension  
Use: Adventure Works (Shared Steps), AW Future (Shared Steps), AW Current (Shared Steps)  
Indexed: False

    O parâmetro Use indica o nome de cada projeto e o tipo de item de trabalho onde o campo é usado. Para obter mais informações sobre atributos de campo, consulte Índice de campos de item de trabalho.

Listar todos os campos em uma coleção de projetos

  • Digite o comando a seguir para listar todos os campos definidos para uma coleção de projetos.

    witadmin listfields /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection

    As informações de campo de todos os campos da coleção de projetos nomeados são exibidas. Consulte Índice de campos de item de trabalho.

Listar campos que não estão sendo usados

  • Digite o comando a seguir para listar os campos que não estão mais sendo usados na coleção de projetos por qualquer tipo de item de trabalho.

    witadmin listfields /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /unused

    As informações de campo e atributo aparecem para cada campo que não está sendo usado, conforme mostrado neste exemplo.

    Field: Microsoft.VSTS.CMMI.TaskType  
Name: Task Type  
Type: String  
Reportable As: dimension  
Use: Not In Use  
Indexed: False  

Field: Microsoft.VSTSUE.Common.Flag  
Name: Flag  
Type: String  
Reportable As: dimension  
Use: Not In Use  
Indexed: False  

Field: Microsoft.VSTSUE.Common.Progress  
Name: Progress  
Type: String  
Reportable As: dimension  
Use: Not In Use  
Indexed: False

Renomear um campo

Você pode alterar o nome amigável de um campo de item de trabalho para atender às convenções de nomenclatura que sua equipe usa. Observe que o novo nome é aplicado a todos os tipos de item de trabalho que fazem referência ao campo alterado em todos os projetos na coleção de projetos. O nome amigável é exibido quando você define critérios de filtro em uma consulta de item de trabalho. O nome que aparece em um formulário de item de trabalho pode ser diferente do nome amigável definido para o campo.

Para renomear um campo de item de trabalho

  1. Digite o seguinte comando para renomear o nome amigável atribuído a Microsoft.VSTS.Common.RankClassificação Importante.

    witadmin changefield /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:Microsoft.VSTS.Common.Rank /name:"Important Rank"

  2. No prompt de confirmação, digite y e pressione ENTER. Aguarde até receber a seguinte mensagem:

    Campo renomeado.

Para verificar as alterações importadas para um único projeto

  1. No Team Explorer, escolha AtualizarAtualizar.

    As atualizações mais recentes são baixadas do servidor, que incluem as alterações que você acabou de fazer no nome do campo. Aguarde alguns segundos até que a atualização seja concluída.

  2. Escolha Nova Consulta para criar uma consulta.

  3. No Editor de Consultas, escolha o link Clique aqui para adicionar uma cláusula para adicionar uma linha, selecione a célula Campo em branco e, na célula, digite Classificação. A seguinte mensagem que aparece acima da lista de resultados. Esta mensagem indica que a classificação não pode ser encontrada.

    Execute a consulta para ver os resultados da consulta. TF51005: A consulta faz referência a um campo que não existe. O erro é causado por <<Rank>>.

  4. Exclua o valor Classificação da célula Campo e digite Classificação Importante na célula.

  5. Selecione <> na célula Operador e digite 1 na célula Valor.

  6. Na barra de ferramentas Consulta , escolha Executar ConsultaExecutar.

  7. Abra o menu de atalho para qualquer linha nos resultados e selecione Opções de coluna. Desloque-se para baixo na lista Colunas disponíveis. Observe que o campo Classificação não está mais presente, mas o campo Classificação importante está presente.

  8. Selecione Classificação importante na caixa Colunas disponíveis e escolha o > botão (adicionar colunas selecionadas). Escolha OK.

    Observe que o nome amigável para Microsoft.VSTS.Common.Rank foi renomeado de Rank para Important Rank em todo o construtor de consultas e a lista de resultados.

  9. Feche a consulta. Escolha Não quando for solicitado a salvar a consulta.

  10. Crie um novo item de trabalho Tarefa. Escolha o link Novos Itens de Trabalho e, em seguida, escolha Tarefa.

    Este item de trabalho é criado a partir do tipo de item de trabalho que você alterou e importou.

  11. Observe, na caixa Status , que o rótulo do campo renomeado, Classificação, não foi alterado. Isso ocorre porque os rótulos de campo nos formulários de item de trabalho têm escopo para o projeto pai e são independentes do nome de campo em todo o servidor recém-especificado.

    Nota

    Para obter mais informações sobre como alterar rótulos de campo em formulários de item de trabalho, consulte Referência de elemento XML de controle.

  12. Feche a nova Tarefa e escolha Não quando for solicitado a salvar o item de trabalho.

Alterar o relatório como valor de um campo

O comando a seguir especifica a capacidade de relatar o tipo do campo DateTime AdventureWorks.CreatedOn para a dimensão. Os dados desse campo entram no depósito e nos bancos de dados do Analysis Services para que possam ser usados para filtrar relatórios.

witadmin changefield /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:AdventureWorks.CreatedOn /reportingtype:dimension

O comando a seguir especifica a capacidade de relatar o tipo de campo duplo AdventureWorks.Field a ser medido. Todas as medidas são agregadas por soma.

witadmin reportfield /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:AdventureWorks.Field /reportingtype:measure

Habilitar a sincronização de um campo personalizado de nome de pessoa

O comando a seguir habilita a sincronização para o campo de item de trabalho AW. CustomerName definido para Collection1 no AdventureWorksServer.

Verifique o tipo de dados do campo que você deseja converter

  1. Verifique o tipo de dados atribuído ao campo, como MyCompany.CustomerName, que você deseja sincronizar inserindo o seguinte comando:

    witadmin listfields /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:MyCompany.CustomerName

Ativar sincronização

  1. Para habilitar a sincronização de um campo nomeado por pessoa, digite o seguinte comando, substituindo seus dados pelos argumentos mostrados aqui:

    witadmin changefield /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:MyCompany.CustomerName /syncnamechanges:true

  2. O seguinte prompt de confirmação é exibido:

    Isso alterará as propriedades do campo {0} no Team Foundation Server. Quer continuar?

  3. Digite 0 para confirmar que deseja alterar o campo ou 1 para cancelar a solicitação.

    Se a solicitação de alteração for bem-sucedida, a seguinte mensagem de confirmação será exibida:

    O campo foi atualizado.

    Se a solicitação de alteração falhar, uma mensagem de erro será exibida. Os erros mais comuns que podem ser cometidos são tentar alterar um campo de referência do sistema ou tentar alterar um campo de um tipo de dados diferente de String. Estas operações não são suportadas.

Eliminar um campo

Antes de excluir um campo, verifique se ele não está em uso. Se o campo estiver em uso, você deve primeiro removê-lo dos tipos de item de trabalho que o usam antes de excluí-lo da coleção de projetos. O comando a seguir exclui o campo AdventureWorks.Field de Collection1:

witadmin deletefield /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:AdventureWorks.Field

Verificar se um campo não está em uso

  1. Digite o comando a seguir, especificando o nome de referência para o campo de item de trabalho, como MyCompany.MyProcess.MyField.

    witadmin listfields /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:MyCompany.MyProcess.MyField

    Nas informações exibidas para o campo, verifique se o valor para Use é "Not In Use" como segue neste exemplo.

    Field: MyCompany.MyProcess.MyField  
Name: MyField  
Type: String  
Reportable As: dimension  
Use: Not In Use  
Indexed: False

  2. Se o campo Usar indicar que o campo está em uso, você deverá excluí-lo de cada tipo de item de trabalho para cada projeto listado. Por exemplo, o Microsoft.VSTS.TCM.SystemInfo campo indica que ele está sendo usado pelos tipos de item de trabalho Bug e Code Defect para quatro projetos: Arroyo, Desert, Palm e Springs.

    Field: Microsoft.VSTS.TCM.SystemInfo  
Name: System Info  
Type: Html  
Reportable As: None  
Use: Arroyo (Bug), Desert (Bug), Palm (Bug), Springs (Bug, Code Defect)  
Indexed: False

    Antes de excluir esse campo, você deve removê-lo de cada um dos tipos de item de trabalho listados para cada projeto para o qual ele está definido. Para remover o campo, modifique a definição para o tipo de item de trabalho excluindo os FIELD elementos e Control que contêm o nome de referência do campo. Consulte Importar, exportar e gerenciar tipos de item de trabalho, Referência de elemento FIELD (Definição) e Controle.

Excluir um campo de uma coleção de projetos

Digite o seguinte comando para excluir o MyCompany.MyProcess.MyField campo e escolha Enter.

witadmin deletefield /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:RefName

Digite y no prompt de confirmação para concluir esta etapa.