Partilhar via

Definições de itens

MSBuild 2.0 permite a declaração estática de itens em arquivos de projeto usando o elemento ItemGroup . No entanto, os metadados só podem ser adicionados ao nível do item, mesmo que os metadados sejam idênticos para todos os itens. A partir do MSBuild 3.5, um elemento de projeto chamado ItemDefinitionGroup supera essa limitação. ItemDefinitionGroup permite definir um conjunto de definições de item, que adicionam valores de metadados padrão a todos os itens no tipo de item nomeado.

O elemento ItemDefinitionGroup aparece imediatamente após o elemento Project do arquivo de projeto. As definições de item fornecem a seguinte funcionalidade:

  • Você pode definir metadados padrão globais para itens fora de um destino. Ou seja, os mesmos metadados se aplicam a todos os itens do tipo especificado.

  • Os tipos de item podem ter várias definições. Quando especificações de metadados adicionais são adicionadas ao tipo, a última especificação tem precedência. (Os metadados seguem a mesma ordem de importação que as propriedades seguem.)

  • Os metadados podem ser aditivos. Por exemplo, os valores de CDefines são acumulados condicionalmente, dependendo das propriedades que estão sendo definidas. Por exemplo, MT;STD_CALL;DEBUG;UNICODE.

  • Os metadados podem ser removidos.

  • As condições podem ser usadas para controlar a inclusão de metadados.

Valores padrão de metadados de item

Os metadados de item definidos em um ItemDefinitionGroup são apenas uma declaração de metadados padrão. Os metadados não se aplicam a menos que você defina um Item que usa um ItemGroup para conter os valores de metadados.

Observação

Em muitos dos exemplos neste tópico, um elemento ItemDefinitionGroup é mostrado, mas sua definição ItemGroup correspondente é omitida para clareza.

Os metadados explicitamente definidos em um ItemGroup têm precedência sobre os metadados em ItemDefinitionGroup. Os metadados em ItemDefinitionGroup são aplicados somente para metadados indefinidos em um ItemGroup. Por exemplo:

<ItemDefinitionGroup>
    <i>
        <m>m1</m>
        <n>n1</n>
    </i>
</ItemDefinitionGroup>
<ItemGroup>
    <i Include="a">
        <o>o1</o>
        <n>n2</n>
    </i>
</ItemGroup>

Neste exemplo, os metadados padrão "m" são aplicados ao Item "i" porque os metadados "m" não são explicitamente definidos pelo Item "i". No entanto, os metadados padrão "n" não são aplicados ao Item "i" porque os metadados "n" já estão definidos pelo Item "i".

Observação

Os nomes de elemento XML e parâmetro diferenciam maiúsculas de minúsculas. Os metadados do item e os nomes de Item/Property não diferenciam maiúsculas de minúsculas. Portanto, os itens ItemDefinitionGroup que têm nomes que diferem apenas por maiúsculas e minúsculas devem ser tratados como o mesmo ItemGroup.

Fontes de valor

Os valores para metadados definidos em um ItemDefinitionGroup podem vir de muitas fontes diferentes, da seguinte maneira:

  • Propriedade PropertyGroup

  • Item de um ItemDefinitionGroup

  • Transformação de item em um item ItemDefinitionGroup

  • Variável de ambiente

  • Propriedade global (da linha de comando MSBuild.exe )

  • Propriedade reservada

  • Metadados conhecidos em um Item de um ItemDefinitionGroup

  • Secção <CDATA ![ CDATA[qualquer coisa aqui não é analisada]]>

Observação

Os metadados de item de um ItemGroup não são úteis em uma declaração de metadados ItemDefinitionGroup porque os elementos ItemDefinitionGroup são processados antes dos elementos ItemGroup.

Aditivo e definições múltiplas

Quando você adiciona definições ou usa vários ItemDefinitionGroups, lembre-se do seguinte:

  • Especificação de metadados adicionais é adicionada ao tipo.

  • A última especificação tem precedência.

Quando você tem vários ItemDefinitionGroups, cada especificação subsequente adiciona seus metadados à definição anterior. Por exemplo:

<ItemDefinitionGroup>
    <i>
        <m>m1</m>
        <n>n1</n>
    </i>
</ItemDefinitionGroup>
<ItemDefinitionGroup>
    <i>
        <o>o1</o>
    </i>
</ItemDefinitionGroup>

Neste exemplo, os metadados "o" são adicionados a "m" e "n".

Além disso, valores de metadados previamente definidos também podem ser adicionados. Por exemplo:

<ItemDefinitionGroup>
    <i>
        <m>m1</m>
    </i>
</ItemDefinitionGroup>
<ItemDefinitionGroup>
    <i>
        <m>%(m);m2</m>
    </i>
</ItemDefinitionGroup>

Neste exemplo, o valor previamente definido para metadados "m" (m1) é adicionado ao novo valor (m2), de modo que o valor final é "m1; m2".

Observação

Isso também pode ocorrer no mesmo ItemDefinitionGroup.

Quando você substitui os metadados definidos anteriormente, a última especificação tem precedência. No exemplo a seguir, o valor final dos metadados "m" vai de "m1" a "m1a".

<ItemDefinitionGroup>
    <i>
        <m>m1</m>
    </i>
</ItemDefinitionGroup>
<ItemDefinitionGroup>
    <i>
        <m>m1a</m>
    </i>
</ItemDefinitionGroup>

Condições de uso em um ItemDefinitionGroup

Você pode usar condições em um ItemDefinitionGroup para controlar a inclusão de metadados. Por exemplo:

<ItemDefinitionGroup Condition="'$(Configuration)'=='Debug'">
    <i>
        <m>m1</m>
    </i>
</ItemDefinitionGroup>

Nesse caso, os metadados padrão "m1" no item "i" são incluídos somente se o valor da propriedade "Configuration" for "Debug".

Observação

Apenas referências de metadados locais são suportadas em condições.

As referências a metadados definidos em um ItemDefinitionGroup anterior são locais para o item, não para o grupo de definições. Ou seja, o escopo das referências é específico do item. Por exemplo:

<ItemDefinitionGroup>
    <test>
        <yes>1</yes>
    </test>
    <i>
        <m>m0</m>
        <m Condition="'%(test.yes)'=='1'">m1</m>
    </i>
</ItemDefinitionGroup>

No exemplo acima, o item "i" faz referência ao item "teste" em sua Condição. Essa condição nunca será verdadeira porque o MSBuild interpreta uma referência aos metadados de outro item em um ItemDefinitionGroup como a cadeia de caracteres vazia. Portanto, "m" seria definido como "m0".

  <ItemDefinitionGroup>
    <i>
      <m>m0</m>
      <yes>1</yes>
      <m Condition="'%(i.yes)'=='1'">m1</m>
    </i>
  </ItemDefinitionGroup>

No exemplo acima, "m" seria definido como o valor "m1" como o valor de metadados do item "i" para o item "yes".

Substituir e excluir metadados

Os metadados definidos em um elemento ItemDefinitionGroup podem ser substituídos em um elemento ItemDefinitionGroup posterior definindo o valor de metadados como outro valor. Você também pode excluir efetivamente um item de metadados definindo-o como um valor vazio. Por exemplo:

<ItemDefinitionGroup>
    <i>
        <m>m1</m>
    </i>
</ItemDefinitionGroup>
<ItemDefinitionGroup>
    <i>
        <m></m>
    </i>
</ItemDefinitionGroup>

O item "i" ainda contém metadados "m", mas seu valor agora está vazio.

Âmbito dos metadados

ItemDefinitionGroups tem escopo global em propriedades definidas e globais onde quer que sejam definidas. As definições de metadados padrão em um ItemDefinitionGroup podem ser autorreferenciais. Por exemplo, o seguinte usa uma referência de metadados simples:

<ItemDefinitionGroup>
    <i>
        <m>m1</m>
        <m>%(m);m2</m>
    </i>
</ItemDefinitionGroup>

Uma referência de metadados qualificados também pode ser usada:

<ItemDefinitionGroup>
    <i>
        <m>m1</m>
        <m>%(i.m);m2</m>
    </i>
</ItemDefinitionGroup>

No entanto, o seguinte não é válido:

<ItemDefinitionGroup>
    <i>
        <m>m1</m>
        <m>@(x)</m>
    </i>
</ItemDefinitionGroup>

A partir do MSBuild 3.5, ItemGroups também pode ser autorreferencial. Por exemplo:

<ItemGroup>
    <item Include="a">
        <m>m1</m>
        <m>%(m);m2</m>
    </item>
</ItemGroup>

Conteúdo relacionado

  • Last updated on