Definir listas de opções

Azure DevOps Server 2020 | Azure DevOps Server 2019 | TFS 2018 – TFS 2013

Você pode enumerar um conjunto de valores para um campo definindo uma lista de seleção como parte de sua definição ou em algum momento durante o fluxo de trabalho. Você pode especificar que a lista pode conter apenas valores permitidos, não pode conter valores proibidos ou pode sugerir valores. Se você sugerir valores, os usuários poderão especificar um valor que não esteja na lista de seleção.

Você também pode definir listas de seleção dependentes, nas quais você define duas ou mais listas para um campo, mas apenas uma lista aparece em tempo de execução com base na avaliação de uma regra condicional.

Observação

Para adicionar ou modificar uma lista de seleção para uma FIELD definição, use a ferramenta de linha de comando witadmin para importar e exportar a definição para o tipo de item de trabalho. Consulte importar, exportar e gerenciar tipos de item de trabalho.

Estrutura da sintaxe

Você pode usar os ALLOWEDVALUES elementos, SUGGESTEDVALUES e PROHIBITEDVALUES para especificar uma lista de valores que um usuário deve especificar, pode especificar ou não deve especificar como um valor para um campo. Se você usar cada um desses elementos, poderá enumerar uma lista de itens ou especificar uma lista global. Você pode usar o ALLOWEXISTINGVALUE para permitir que um campo armazene um valor existente se você remover um item da lista de seleção.

Você pode especificar esses elementos como elementos filho do FIELD elemento (definição) ou FIELD (fluxo de trabalho).

  • Você usa ALLOWEDVALUES para definir uma lista de valores que os usuários podem especificar em um formulário de item de trabalho ou no editor de consultas. Os usuários devem especificar um dos valores no GLOBALLIST ou no conjunto de LISTITEM entradas.

    <ALLOWEDVALUES for="userGroupName" not="userGroupName" expanditems="true | false" filteritems="excludegroups">  
          <GLOBALLIST name="globalListName" />  
          <LISTITEM value="Name1" />  
          <LISTITEM value="Name2" />  
          <LISTITEM value="Name3" />  
    . . .   
    </ALLOWEDVALUES>  
    
  • Você usa PROHIBITEDVALUES para definir uma lista de valores que um campo não pode conter. Os usuários não poderão salvar um item de trabalho se o campo contiver um valor proibido. Você usará esse elemento se quiser restringir o uso de um valor que era anteriormente permitido, mas que não é mais válido.

    <PROHIBITEDVALUES for="userGroupName" not="userGroupName" expanditems="true | false" filteritems="excludegroups">  
          <GLOBALLIST name="globalListName" />  
          <LISTITEM value="Name1" />  
          <LISTITEM value="Name2" />  
          <LISTITEM value="Name3" />  
    . . .   
    </PROHIBITEDVALUES>  
    
  • Você usa SUGGESTEDVALUES para definir uma lista de valores que um campo pode conter. Os usuários podem especificar outros valores além daqueles que você sugere.

    <SUGGESTEDVALUES for="userGroupName" not="userGroupName" expanditems="true | false" filteritems="excludegroups">  
          <GLOBALLIST name="globalListName" />  
          <LISTITEM value="Name1" />  
          <LISTITEM value="Name2" />  
          <LISTITEM value="Name3" />  
    . . .   
    </SUGGESTEDVALUES>  
    

    Para cada um desses elementos, você pode especificar um ou mais dos atributos que a tabela a seguir descreve:

Atributo Descrição
for Opcional. Especifica o nome de um usuário ou grupo no Team Foundation ao qual a regra se aplica. Os nomes válidos consistem em uma cadeia de caracteres de texto que contenha entre 1 e 255 caracteres.

Valor do padrão: ^ [^ \ \] + \ \ [^ \ \] + $

Exemplo de valor de padrão: domínio\userid
not Opcional. Especifica o nome de um usuário ou grupo no Team Foundation ao qual a regra não se aplica. Os nomes válidos consistem em uma cadeia de caracteres de texto que contenha entre 1 e 255 caracteres.

Valor do padrão: ^ [^ \ \] + \ \ [^ \ \] + $

Exemplo de valor de padrão: domínio\userid
expanditems Opcional. Especifica se um grupo identificado no elemento ListItem deve ser expandido para incluir grupos subordinados na lista. O valor padrão é true.
filteritems Opcional. Especifica que a lista inclui somente os membros de grupos, não os nomes de grupo. O único valor válido desse atributo é excludegroups .

Para obter mais informações, consulte expandir lista de itens e excluir grupos de listas.

Observação

Para o modelo de processo XML hospedado, os seguintes limites são colocados na importação de lista global:

  • Total de 64 listas globais
  • Total de 512 itens por lista
  • Aproximadamente 10K itens podem ser definidos no total dentro de todas as listas globais especificadas em todos os WITs.

Estrutura de sintaxe para elementos GLOBALlist e LISTITEM

Você pode usar os GLOBALLIST elementos e LISTITEM para enumerar uma lista de itens que podem ser atualizados globalmente ou que sejam específicos para um único campo.

  • Use GLOBALLIST para definir um conjunto de elementos ListItem que é armazenado para uma coleção de projetos e que todos os projetos dessa coleção podem usar. GLOBALLIST é um elemento filho necessário do elemento GLOBALLISTS e um elemento filho opcional dos ALLOWEDVALUES elementos, SUGGESTEDVALUES e PROHIBITEDVALUES . Você pode definir uma lista global dentro de uma definição de item de trabalho, uma definição de lista global, ou um Workflow global.

    <GLOBALLIST name="globalListName">  
          <LISTITEM value="Name1" />  
          <LISTITEM value="Name2" />  
          <LISTITEM value="Name3" />  
    . . .   
    </GLOBALLIST>   
    

    globalListName: uma cadeia de texto que contém entre 1 e 255 caracteres.

    Importante

    Se você definir uma lista global em um arquivo XML que define um tipo de item de trabalho, deverá dar à lista um nome exclusivo. Caso contrário, você pode substituir uma lista existente que foi definida para a coleção.

  • Use ListItem para enumerar um conjunto de valores. ListItem é um elemento filho obrigatório de GLOBALLIST e um elemento filho opcional dos ALLOWEDVALUES elementos, SUGGESTEDVALUES e PROHIBITEDVALUES .

    <LISTITEM value="listName" />  
    

    ListName: uma cadeia de texto que contém entre 1 e 255 caracteres.

Permitir um valor existente

Você pode usar o ALLOWEXISTINGVALUE elemento para permitir que um campo Mantenha os valores existentes, depois de especificar uma lista de seleção de itens usando o ALLOWEDVALUES elemento. Se você não especificar o ALLOWEXISTINGVALUE elemento, forçará o usuário, em hora de edição, a especificar um dos valores válidos atuais para esse campo. O ALLOWEXISTINGVALUE elemento modifica somente os elementos no mesmo bloco.

<ALLOWEXISTINGVALUE />  

Você especifica esse elemento no elemento de campo (fluxo de trabalho) para aplicá-lo às regras definidas para o campo. Esse aplicativo inclui as regras que o estado, a transição, o mesmo motivoe os elementos de motivo do campo especificam. Você especifica esse elemento sob o elemento State para aplicá-lo não apenas às regras que são definidas no estado do campo, mas também às regras que são definidas para o campo para todas as transições no estado.

Você especifica esse elemento sob o elemento Transition para aplicá-lo não apenas às regras que são definidas na transição para o campo, mas também às regras que são definidas para o campo nos elementos REASON e DEFAULTREASON .

Especificar uma lista

As listas de campos são compostas por itens de lista individuais. Cada lista de campos deve conter pelo menos um item.

Observação

As listas globais não devem incluir grupos com escopo do projeto porque eles não têm escopo para um projeto.

Para especificar itens em uma lista de campos, use o <LISTITEM value=""> elemento. Você pode especificar uma cadeia de caracteres, um nome de usuário ou um nome de grupo.

<LISTITEM value="Emergency"/>  
<LISTITEM value="Major"/>  
<LISTITEM value="Minor"/>  
<LISTITEM value="Domain\joe"/>  
<LISTITEM value="[Global]\GlobalGroup" />  
<LISTITEM value="[Project]\ProjectGroup" />  

Observação

em tempo de execução, os itens dentro de uma lista aparecem em ordem alfabética com base no idioma do servidor que está executando Visual Studio Team Foundation Server.

Especificar um conjunto de valores permitidos

Neste exemplo, o campo severidade do cliente pode ter qualquer um dos três valores: emergência, principal e secundária. O campo é definido conforme necessário com um valor padrão de secundário. Em tempo de execução, os usuários podem especificar um dos valores em uma lista suspensa.

<FIELD refname="System.Title" name="Title" type="String">  
<HELPTEXT>Provide a brief description of the work item</HELPTEXT>  
<REQUIRED/>  
</FIELD>  
<FIELD refname="MyCorp.CusSeverity" name="Customer Severity" type="String">  
<HELPTEXT>Indicate the severity of the problem</HELPTEXT>  
       <ALLOWEDVALUES>  
         <LISTITEM value="Emergency">  
         <LISTITEM value="Major">  
         <LISTITEM value="Minor">  
       </ALLOWEDVALUES>  
<DEFAULT from="value" value="Minor"/>  
</FIELD>  

Definir listas de seleção dependentes

Você pode definir uma lista de seleção que está ativa somente quando sua cláusula condicional pai é verdadeira. No exemplo a seguir, dois conjuntos de listas de seleção são definidos para o meu campo. Em tempo de execução, apenas uma lista aparece com base em se os requisitos são atribuídos ao MyCompany.MyTeam.Discipline campo.

Observação

As regras When e WHENNOT neste exemplo também podem se aplicar a outras regras para especificar quando essas regras devem ser avaliadas. Para obter mais informações, consulte Where, WHENNOT, WHENCHANGED e WHENNOTCHANGED XML Elements.

<FIELD name="My Field" refname="MyCompany.MyProcess.MyField" type="String" reportable="dimension">  
  <WHEN field="MyCompany.MyTeam.Discipline" value="Requirements">
    <ALLOWEDVALUES>
      <LISTITEM value="Planning" />
      <LISTITEM value="Review" />
    </ALLOWEDVALUES>
  </WHEN>
  <WHENNOT field=" MyCompany.MyTeam.Discipline" value="Requirements">
    <ALLOWEDVALUES>
      <LISTITEM value="Process Management" />
      <LISTITEM value="Planning" />
      <LISTITEM value="Review" />
    </ALLOWEDVALUES>
  </WHENNOT>  
</FIELD>