Gerenciar campos de item de trabalho

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

A ferramenta de linha de comando witadmin fornece recursos poderosos para gerenciar campos de item de trabalho em sua coleção de projetos. Se você precisa renomear campos, ajustar tipos de dados ou configurar a sincronização com provedores de identidade, esses comandos oferecem controle granular sobre sua experiência de acompanhamento de trabalho.

O que você pode fazer com os comandos de campo witadmin

Use os seguintes comandos witadmin para gerenciar campos em todos os tipos de item de trabalho e projetos em sua coleção:

• changefield: Modificar atributos de campo que se aplicam a toda a coleção, incluindo:
  • Conversão de tipo de dados entre PlainText e HTML formatos

  Importante

  Quando você atualiza o Servidor de DevOps do Azure, o campo Descrição (System.Description) é convertido automaticamente de PlainText para HTML. Use o changefield comando para reverter isso, se necessário.

  • Nomes amigáveis exibidos em consultas de item de trabalho (podem diferir dos rótulos de formulário)
  • Atributos de relatório para integração de data warehouse
  • Sincronização de identidade com o Microsoft Entra ID ou Ative Directory
• deletefield: Remover campos não utilizados da sua coleção
• listfields: Exibir atributos de campo e uso em projetos

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.

Para o Visual Studio 2022

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

Professional ou Enterprise 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

Professional ou Enterprise 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

TeamExplorer ou Professional 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.

Pré-requisitos

Para obter mais informações, consulte Alterar as permissões ao nível da coleção de projetos.

Sintaxe

Use os seguintes padrões de sintaxe de comando para gerenciar campos de item de trabalho com a ferramenta witadmin:

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

Sincronizando nomes de pessoas com o Microsoft Entra ID e o Ative Directory

Configure campos personalizados de nome de pessoa para atualizar automaticamente quando os nomes de usuário forem alterados em seu provedor de identidade.

Quando ativar a sincronização

Somente campos personalizados: você deve habilitar manualmente a sincronização para todos os campos de item de trabalho personalizados usados para atribuir nomes de pessoas.

Campos do sistema: Todos os campos internos de nome de pessoa têm automaticamente a sincronização ativada:

• System.AssignedTo
• System.ChangedBy
• System.CreatedBy

Suporte ao provedor de identidade

Como funciona a sincronização

Restrições de nome de grupo

Quando você habilita o syncnamechanges atributo em um campo String, ele aceita nomes de usuário válidos, mas não permite nomes de grupo se qualquer uma destas condições se aplicar:

• VALIDUSER regra especificada em todos os tipos de item de trabalho
• VALIDUSER regra especificada para um tipo de item de trabalho específico
• ALLOWEDVALUES Regra especificada com critérios de filtro que exclui grupos

Âmbito da configuração

Para obter mais informações, consulte:

• Campos de atribuições e fluxo de trabalho
• 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 são exibidas 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. 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 selecione ENTER. Aguarde até receber a seguinte mensagem:

   Campo renomeado.

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

1. No Team Explorer, escolha Atualizar.

   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 Rank. 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 insira Important Rank na célula.

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

6. Na barra de ferramentas Consulta , escolha Executar.

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 é renomeado de Rank para Important Rank em todo o construtor de consultas e 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. 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 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

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 Servidor de DevOps do Azure. Quer continuar?

3. Entre 0 para confirmar que deseja alterar o campo ou 1 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. Essas 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 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.

Artigos relacionados

• Personalizar a sua experiência de acompanhamento de trabalho
• Índice do campo dos itens de trabalho
• witAdmin: Personalize e gerencie objetos para acompanhar o trabalho