Gerenciar campos de item de trabalho [witadmin]

Artigo
06/09/2015

Você pode gerenciar os campos de tipos de itens de trabalho definidos para uma coleção de projetos de equipe usando os seguintes comandos witadmin:

changefield: Altera um ou mais atributos de um campo. Ao alterar um dos seguintes atributos, você altera todos os tipos de itens de trabalho e projetos de equipe dentro da coleção de projetos de equipe:
- Tipo de dados para os campos PlainText ou HTML.
  
  Importante
  
  Quando você atualiza 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) é automaticamente convertida de PlainText para HTML.Você pode restaurar o conteúdo desse campo para exibir texto simples com o comando changefield.
- Nome amigável que é exibido na consulta de item de trabalho. Esse nome pode diferir 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 Active Directory, você pode habilitar/desabilitar a sincronização de campos de nomes de pessoas.
deletefield: Exclui o campo especificado.
indexfield: Ativa ou desativa a indexação para o campo especificado. Quando você habilita a indexação de um campo, pode aumentar o desempenho de localização de itens de trabalho cujas consultas especificam esse campo. Se adicionar um campo personalizado usado em várias das consultas de itens de trabalho, talvez queira habilitar a indexação para esse campo.
listfields: Lista os atributos de todos os campos ou de um campo especificado.

Para executar a ferramenta da linha de comandos witadmin, abra uma janela do Prompt de Comando em que Visual Studio ou Team Explorer esteja instalado e insira:

cd %programfiles(x86)%\Microsoft Visual Studio 12.0\Common7\IDE

Em uma edição de 32 bits do Windows, substitua %programfiles(x86)% por %programfiles%.

Para obter uma visão geral dos campos definidos com os modelos de processo padrão fornecidos com Team Foundation Server, veja Referência de campo de item de trabalho do Visual Studio ALM.

Dica

Você pode criar e modificar campos de itens de trabalho usando o Editor de Processo, uma poderosa ferramenta para Visual Studio.Essa ferramenta não é compatível.Para obter mais informações, consulte a página a seguir no site da Microsoft: Ferramentas Poderosas do Team Foundation Server.

Requisitos

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

Para obter mais informações, consulte Referência de permissões para o Team Foundation Server.

Dica

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

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 indexfield /collection:CollectionURL /n:Name /index:on|off 

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

Parâmetros

Parâmetro	Descrição
/collection:CollectionURL	Especifica o URI da coleção de projeto de equipe. O formato do URI é o seguinte: http://ServerName:Port/VirtualDirectoryName/CollectionName Se nenhum diretório virtual for usado, então o formato do URI será o seguinte: 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 do campo especificado. Especifica on para habilitar a indexação e off para desabilitar a indexação.
/name:NewName	Especifica o novo nome do caminho.
/syncnamechanges	Especifica o uso do campo de item de trabalho para armazenar nomes e atualizar, a medida que as mudanças forem feitas no Active Directory ou em um grupo de trabalho. Essa opção é válida somente quando um campo com o tipo de dados de Cadeia de Caracteres for especificado para o typename. Especifique true para habilitar a sincronização do 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 no relatório.
/reportingrefname:ReportingRefName	Especifica o nome da referência do campo no data warehouse a ser usado no relatório.
/reportingtype:Type	Especifica como o campo é usado no warehouse do relatório. Os seguintes valores são válidos: dimension: Usado nos campos Número Inteiro, Cadeia de Caracteres ou Datahora. detail: Usado nos campos Número Inteiro, Duplo, Cadeia de Caracteres ou Datahora. measure: Usado nos campos Número Inteiro e Duplo. O tipo de agregação padrão é soma. Você pode especificar outro tipo de agregação usando o parâmetro formula. none: Usado para desabilitar reportabilidade no campo. Para obter mais informações, consulte Definir e modificar campos do item de trabalho.
/reportingformula:Formula	Especifica a fórmula de agregação a ser usada quando o campo é relatado como uma measure. A única fórmula compatível é sum.
/type:HTML \| PlainText	Especifica para converter o conteúdo do campo de PlainText em HTML ou de HTML em PlainText. Você pode especificar essa opção somente para os campos cuja atribuição de tipo seja PlainText ou HTML. Consulte Referência de elemento FIELD (definição).
/unused	Lista todos os campos que não são usados por nenhum projeto de equipe definido na coleção de projetos de equipe.
/noprompt	Desabilita o prompt para confirmação.
/? or help	Exibe ajuda sobre o comando na janela Prompt de comando.

Comentários

Campos indexados

Um índice de consulta é criado com base nesses campos que tenham a indexação habilitada. Esse índice melhora o tempo de resposta ao executar consultas que incluem campos indexados.

Por padrão, os seguintes campos são indexados: Atribuído a, Data de Criação, Alterado por, Estado, Motivo, ID da Área, ID da Iteração e Tipo de Item de Trabalho. Se houver outros campos que sua equipe utiliza com frequência em suas consultas, você pode adicioná-los ao índice da consulta.

Sincronizando nomes de pessoas com o Active Directory

Você deve habilitar a sincronização de quaisquer campos de itens de trabalho personalizados que sejam usados para atribuir nomes de pessoas que fazem referência ao Active Directory. Você deve habilitar a sincronização de cada campo para cada coleção de projetos de equipe que contenham os campos personalizados.

Todos os campos de referência do sistema que mostram nomes de pessoas que tenham o atributo syncnamechanges definido como true. Esses campos incluem System.AuthorizedAs, System.AssignedTo, System.ChangedBy e System.CreatedBy. A sincronização é habilitada 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 referência de campos de fluxo de trabalho.

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

Quando você designa o atributo syncnamechanges a um campo Cadeia de Caracteres, o campo sempre aceita os nomes de usuários válidos. No entanto, os campos não permitirão nomes de grupos que estejam armazenados no Team Foundation Server ou no Active Directory se alguma das seguintes condições for true:

A regra VALIDUSER é especificada em todos os tipos de itens de trabalho
A regra VALIDUSER é especificada para um tipo de item de trabalho
A regra ALLOWEDVALUES é especificada para um tipo de item de trabalho e essa regra possui um critério de filtro que exclui grupos

Para obter mais informações, consulte Todas as referências de elementos XML 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 do tipo de item de trabalho no qual o campo aparece:

Nome que é exibido no formulário do item de trabalho. Consulte Referência do elemento XML de controle.
Texto de ajuda. Consulte Aplicar uma regra a um campo do item de trabalho.
Valores ou itens permitidos dentro de uma lista de opções ou um menu suspenso. Consulte Definir listas de opções.

Exemplos

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

URI da coleção do projeto de equipe: 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 e para selecionar um para adicionar a um tipo de item de trabalho. Além disso, você pode relacionar as designações de atributos definidas para um campo específico e determinar quais campos são usados por quais projetos de equipe.

Exibir os atributos de um campo de item de trabalho

Inserir o comando a seguir para relacionar os atributos definidos para um campo especificado, tal 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 Referência de campo de item de trabalho do Visual Studio ALM.

Relacionar todos os campos em uma coleção de projetos de equipe

Insira o comando a seguir para relacionar todos os campos definidos para uma coleção de projetos de equipe.
```
witadmin listfields /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection
```
As informações sobre o campo de todos os campos da coleção de projetos nomeados são exibidas. Consulte Referência de campo de item de trabalho do Visual Studio ALM.

Relacionar campos que não estão sendo usados

Insira o comando a seguir para relacionar todos os campos que não estão mais sendo usados na coleção de projetos de equipe por nenhum tipo de item de trabalho.

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

As informações de campo e atributo aparecem em 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 utiliza. Observe que o novo nome é aplicado a todos os tipos de itens de trabalho que fazem referência ao campo alterado em todos os projetos de equipe 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

Insira o comando a seguir para renomear o nome amigável atribuído ao 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, digite y e pressione ENTER. Aguarde até receber a seguinte mensagem:

Field renamed.

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

No Team Explorer, escolha Atualizar.

As atualizações mais recentes são baixadas do servidor, o que inclui as alterações que você acabou de fazer no nome do campo. Aguarde vários segundos até que a atualização termine.
Escolha Nova Consulta para criar uma consulta.
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 mensagem a seguir que aparece acima da lista de resultados. Essa mensagem indica que a Classificação não foi localizada.

Execute a consulta para ver os resultados dela. TF51005: A consulta faz referências a um campo que não existe. O erro é causado por <<Classificação>>.
Exclua o valor Classificação da célula Campo e digite Classificação Importante na célula.
Selecione <> na célula Operador e digite 1 na célula Valor.
Na barra de ferramentas de Consulta, escolha Executar.
Abra o menu de atalho de qualquer linha nos resultados e selecione Opções de Coluna. Role para baixo na lista de 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, em seguida, escolha o botão > (adicione colunas selecionadas). Escolha OK.

Observe que o nome amigável para Microsoft.VSTS.Common.Rank foi renomeado de Classificação para Classificação Importante em todo o construtor de consultas e na lista de resultados.
Feche a consulta. Escolha Não quando for solicitado a salvar a consulta.
Crie um novo item de trabalho Tarefa. Escolha o link Novos Itens de Trabalho e 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 do campo renomeado, Classificação, não foi alterado. Isso se deve ao fato de os rótulos de campos nos formulários de itens de trabalho terem escopo no projeto de equipe pai e serem independentes do nome do campo em todo o servidor recém-especificado.

Dica

Para obter mais informações sobre como alterar os rótulos do campo nos formulários de itens de trabalho, veja Referência do elemento XML de controle.
Feche a nova Tarefa e escolha Não quando for solicitado a salvar 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 Datahora AdventureWorks.CreatedOn para dimensão. Os dados desse campo são inseridos nos bancos de dados do warehouse e 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 para medida. Todas as medidas são agregadas pela soma.

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

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

O comando a seguir habilita a sincronização do campo de item de trabalho AW.CustomerName definido para Coleção1 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 deseja sincronizar inserindo o seguinte comando:
```
witadmin listfields /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:MyCompany.CustomerName
```

Habilitar sincronização

Para habilitar a sincronização para um campo de nome de pessoa, digite o seguinte comando, substituindo os 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 aparece:

This will change properties for field {0} on the Team Foundation Server. Do you want to continue?
Digite 0 para confirmar se 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:

The field was updated.

Se a solicitação de alteração falhar, uma mensagem de erro será exibida. Os enganos mais comuns que podem ser feitos são tentar alterar um campo de referência do sistema ou tentar alterar um campo de um tipo de dados diferente da Cadeia de Caracteres. Essas operações não são compatíveis.

Excluir um campo

Antes de excluir um campo, verifique se ele não está em uso. Se o campo estiver em uso, você deve primeiro remover o campo dos tipos de item de trabalho que o utilizam antes de excluí-lo da coleção de projetos de equipe. O seguinte comando exclui o campo AdventureWorks.Field da Coleção1:

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

Verificar se o campo não está em uso

Insira o seguinte comando, especificando o nome de referência do campo item de trabalho, como MyCompany.MyProcess.MyField.

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

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

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

Se o campo Use indicar que o campo está em uso, então você tem que excluí-lo de cada tipo de item de trabalho, de cada projeto de equipe relacionado. Por exemplo, o campo Microsoft.VSTS.TCM.SystemInfo indica que ele está sendo usado pelos tipos de itens de trabalho Bug e Defeitos de Código de 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 poder excluir esse campo, você tem que removê-lo de cada um dos tipos de itens de trabalho relacionados em cada projeto de equipe para o qual ele está definido. Para remover o campo, modifique a definição do tipo de item de trabalho excluindo os elementos FIELD e Control que contêm o nome de referência do campo. Consulte Importar, exportar e gerenciar tipos de item de trabalho [witadmin], Referência de elemento FIELD (definição) e Referência do elemento XML de controle.

Excluir um campo de uma coleção de projetos de equipe

Insira o seguinte comando para excluir o campo MyCompany.MyProcess.MyField e, em seguida, escolha Enter.
```
witadmin deletefield /collection:http://AdventureWorksServer:8080/tfs/DefaultCollection /n:RefName
```
Insira y no prompt de confirmação para concluir esta etapa.

Perguntas e respostas

P: Quais personalizações posso fazer e ainda assim usar o assistente Configurar Recursos para atualizar meu projeto de equipe após uma atualização do TFS?

R: Você pode adicionar campos personalizados, personalizar uma lista de opções e adicionar regras a um campo. O assistente Configurar Recursos atualizará seus projetos de equipe e você terá acesso aos recursos mais recentes.

A alteração de atributos do campo não é recomendada. Para aprender sobre quais personalizações pode fazer com segurança e quais evitar, veja Personalizar a experiência de acompanhamento de trabalho: antes que você personalize, considere as implicações de manutenção e atualização.

Consulte também

Conceitos

Resolver conflitos de esquema que estão ocorrendo no data warehouse

Adicionar ou modificar campos de itens de trabalho para oferecer suporte a relatórios

Referência de campo de item de trabalho do Visual Studio ALM

Referência de campos de relatório para o Visual Studio ALM

Outros recursos

witAdmin: personalizar e gerenciar objetos para acompanhar trabalho

Compartilhar via