Gerenciar campos de item de trabalho

Azure DevOps Services | Servidor Azure DevOps | Azure DevOps Server 2022

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 é compatível, consulte Personalizar sua experiência de acompanhamento de trabalho.

A ferramenta de linha de comando witadmin fornece recursos avançados 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 fornecem controle granular sobre sua experiência de acompanhamento de trabalho.

O que você pode fazer com 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: modifique os atributos de campo que aplicam toda a coleção, incluindo:
- Conversão de tipo de dados entre formatos e entre PlainTextHTML
Importante

Quando você atualiza o Servidor do Azure DevOps, o campo Descrição (System.Description) converte automaticamente em PlainTextHTML. Use o changefield comando para reverter isso, se necessário.
- Nomes amigáveis exibidos em consultas de item de trabalho (podem ser diferentes dos rótulos de formulário)
- Atributos de relatório para integração de data warehouse
- Sincronização de identidade com a ID do Microsoft Entra ou o Active Directory
deletefield: remova campos não utilizados de sua coleção
listfields: exibir atributos de campo e uso entre projetos

Dica

Para adicionar campos globais em ambientes XML locais, modifique o arquivo de fluxo de trabalho global e importe-o para sua coleção.
O witadmin indexfield comando foi preterido. A indexação de campo ocorre automaticamente.

Executar a `witadmin` ferramenta de linha de comando

Para executar a ferramenta de linha de comando, abra uma janela do Prompt de Comando em que 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.

Observação

Para se conectar ao Azure DevOps Services, recomendamos que você use a versão mais recente do Visual Studio ou do Visual Studio Community.

Observação

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

Para Visual Studio 2022

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

ou Professional ou Enterprise no lugar de Community, dependendo da versão que você instalou.

Para Visual Studio 2019

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

ou Professional ou Enterprise no lugar de Community, dependendo da versão que você instalou.

Para Visual Studio 2017

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

ou TeamExplorer ou Professional no lugar de Enterprise, dependendo da versão que você instalou.

Em uma 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.

Dica

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

Pré-requisitos

Tarefa	Permissões necessárias
Listar campos	Exibir a permissão de informações no nível do projeto definida como Permitir para o projeto na coleção
Excluir ou renomear campos	Membro do grupo de segurança Administradores de Coleção de Projetos
Alterar atributos de campo	Membro do grupo de segurança Administradores de Coleção de Projetos

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

Observação

Mesmo se você entrar com permissões administrativas, deverá abrir uma janela do Prompt de Comando com privilégios elevados para executar essa função em um servidor que esteja executando o Windows Server. Para abrir uma janela de Prompt de Comando com privilégios elevados, escolha Iniciar, abra o menu de atalho do Prompt de Comando e escolha Executar como Administrador.

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

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.
`/name:NewName`	Especifica o novo nome do campo.
`/syncnamechanges`	Especifica usar o campo de item de trabalho para armazenar nomes e atualizar conforme as alterações são feitas na ID do Microsoft Entra, no Active Directory ou em um grupo de trabalho. Essa 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 é sum. 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 `measure`. A única fórmula suportada é `sum`.
`/type:HTML` \| `PlainText`	Especifica a conversão do 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 seja `PlainText` ou `HTML`. Consulte Referência do elemento FIELD (Definição).
`/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 a ajuda sobre o comando na janela do Prompt de Comando.

Sincronizando nomes de pessoas com a ID do Microsoft Entra e o Active Directory

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

Quando habilitar a sincronização

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

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

System.AssignedTo
System.ChangedBy
System.CreatedBy

Suporte do provedor de identidade

Ambiente	Provedor de Identidade
Serviços do Azure DevOps	Microsoft Entra ID
Servidor do Azure DevOps	Active Directory ou grupo de trabalho

Como funciona a sincronização

Estado	Comportamento
Antes de habilitar	O campo mostra cadeias de caracteres de texto estático
Depois de habilitar	O campo exibe o nome de usuário atual do provedor de identidade
Quando os nomes são alterados	Campos com `syncnamechanges=true` atualização automática

Restrições de nome de grupo

Quando você habilita o syncnamechanges atributo em um campo Cadeia de caracteres, ele aceita nomes de usuário válidos, mas não permite nomes de grupo se qualquer uma dessas 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

Escopo de configuração

Importante

Você deve habilitar a sincronização para cada campo em cada coleção de projetos que contém os campos personalizados.

Para obter mais informações, consulte:

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 que é 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 seleção ou menu suspenso. Consulte Elementos XML ALLOWEDVALUES, SUGGESTEDVALUES e PROHIBITEDVALUES.

Exemplos

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

URI para a coleção do projeto: http://AdventureWorksServer:8080/tfs/DefaultCollection
Nome do campo de 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

Insira 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 do campo e do 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 Uso indica o nome de cada projeto e o tipo de item de trabalho em que 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

Insira 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 para 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

Insira 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 da 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

Insira o comando a seguir para renomear o nome amigável atribuído a Microsoft.VSTS.Common.Rank para Classificação Importante.

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

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

Campo renomeado.

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

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 para que a atualização termine.
Escolha New Query (Nova consulta ) para criar uma consulta.
No Editor de Consultas, escolha o clique aqui para adicionar um link de cláusula para adicionar uma linha, selecione a célula Campo em branco e, na célula, insira Rank. A mensagem a seguir 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>>.
Exclua o valor Classificação da célula Field e insira Important Rank na célula.
Selecione <> na célula Operador e insira 1 na célula Valor .
Na barra de ferramentas Consulta, escolha Executar.
Abra o menu de atalho de qualquer linha nos resultados e selecione Opções de coluna. Role 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.
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. A classificação é renomeada de Classificação para Classificação Importante em toda a lista de resultados e construtor de consultas.
Feche a consulta. Escolha Não quando for solicitado que você salve a consulta.
Crie um novo item de trabalho de tarefa. Escolha o link Novos Itens de Trabalho e, em seguida, escolha Tarefa.

Esse item de trabalho é criado a partir do tipo de item de trabalho que você alterou e importou.
Observe, na caixa Status , que o rótulo da Classificação do campo renomeado não foi alterado. Os rótulos de campo nos formulários de item de trabalho têm como escopo o projeto pai e são independentes do nome do campo de todo o servidor especificado.

Observação

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.
Feche a nova Tarefa e escolha Não quando for solicitado que você salve o item de trabalho.

Alterar o relatório como valor para 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 warehouse 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 do campo duplo AdventureWorks.Field a ser medido. Todas as medidas agregam por soma.

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

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

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

Para habilitar a sincronização de um campo com nome de 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  
```
O seguinte prompt de confirmação é exibido:

Isso alterará as propriedades do campo {0} no Servidor do Azure DevOps. Deseja continuar?
Insira 0 para confirmar se você 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. Não há suporte para essas operações.

Excluir um campo

Antes de excluir um campo, verifique se o campo não está em uso. Se o campo estiver em uso, primeiro você deverá remover o campo 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

Insira 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 de Uso é "Não em uso" da seguinte maneira neste exemplo.

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

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 Defeito de Código 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 é definido. Para remover o campo, modifique a definição do 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

Insira o comando a seguir para excluir o MyCompany.MyProcess.MyField campo e escolha Enter.

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

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

Comentários

Esta página foi útil?

Last updated on 2025-12-17

Compartilhar via

Gerenciar campos de item de trabalho

O que você pode fazer com comandos de campo witadmin

Executar a witadmin ferramenta de linha de comando

Pré-requisitos

Sintaxe

Parâmetros

Sincronizando nomes de pessoas com a ID do Microsoft Entra e o Active Directory

Quando habilitar a sincronização

Suporte do provedor de identidade

Como funciona a sincronização

Restrições de nome de grupo

Escopo de configuração

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

Exemplos

Listar campos

Exibir os atributos de um campo de item de trabalho

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

Listar campos que não estão sendo usados

Renomear um campo

Para renomear um campo de item de trabalho

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

Alterar o relatório como valor para um campo

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

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

Ativar sincronização

Excluir um campo

Verificar se um campo não está em uso

Excluir um campo de uma coleção de projetos

Artigos relacionados

Comentários

Recursos adicionais

Executar a `witadmin` ferramenta de linha de comando