Comparar propriedades e itens

Propriedades e itens do MSBuild são usados para passar informações para tarefas, avaliar condições e armazenar valores que podem ser referenciados em todo o arquivo de projeto.

• As propriedades são pares nome-valor. Para obter mais informações, confira Propriedades do MSBuild.

• Itens são objetos que normalmente representam arquivos. Objetos de item podem ter coleções de metadados associadas. Metadados são pares nome-valor. Para obter mais informações, consulte Itens.

Escalares e vetores

Como as propriedades do MSBuild são pares nome-valor que têm apenas um valor de cadeia de caracteres, elas geralmente são descritas como escalares. Como os tipos de item do MSBuild são listas de itens, eles geralmente são descritos como vetor. No entanto, na prática, as propriedades podem representar vários valores e os tipos de item podem ter zero ou um itens.

Injeção de dependência de destino

Para ver como as propriedades podem representar vários valores, considere um padrão de uso comum para adicionar um destino a uma lista de destinos a serem criados. Essa lista normalmente é representada por um valor de propriedade, com os nomes de destino separados por ponto-e-vírgula.

<PropertyGroup>
    <BuildDependsOn>
        BeforeBuild;
        CoreBuild;
        AfterBuild
    </BuildDependsOn>
</PropertyGroup>

A BuildDependsOn propriedade normalmente é usada como o argumento de um atributo de destino DependsOnTargets , convertendo-a efetivamente em uma lista de itens. Essa propriedade pode ser substituída para adicionar um destino ou alterar a ordem de execução de destino. Por exemplo

<PropertyGroup>
    <BuildDependsOn>
        $(BuildDependsOn);
        CustomBuild;
    </BuildDependsOn>
</PropertyGroup>

adiciona o destino CustomBuild à lista de destino, dando BuildDependsOn o valor BeforeBuild;CoreBuild;AfterBuild;CustomBuild.

A partir do MSBuild 4.0, a injeção de dependência de destino é preterida. Em vez disso, use o AfterTargets atributo e BeforeTargets . Para obter mais informações, consulte a ordem de build de destino.

Conversões entre cadeias de caracteres e listas de itens

O MSBuild executa conversões de e para tipos de item e valores de cadeia de caracteres, conforme necessário. Para ver como uma lista de itens pode se tornar um valor de cadeia de caracteres, considere o que acontece quando um tipo de item é usado como o valor de uma propriedade MSBuild:

<ItemGroup>
    <OutputDir Include="KeyFiles\;Certificates\" />
</ItemGroup>
<PropertyGroup>
    <OutputDirList>@(OutputDir)</OutputDirList>
</PropertyGroup>

O tipo de item OutputDir tem um Include atributo com o valor "KeyFiles\; Certificados\". O MSBuild analisa essa cadeia de caracteres em dois itens: KeyFiles\ e Certificates\. Quando o tipo de item OutputDir é usado como o valor da propriedade OutputDirList, o MSBuild converte ou "nivela" o tipo de item na cadeia de caracteres separada por ponto-e-vírgula "KeyFiles\; Certificados\".

Propriedades e itens em tarefas

Propriedades e itens são usados como entradas e saídas para tarefas do MSBuild. Para obter mais informações, consulte Tarefas.

As propriedades são passadas para tarefas como atributos. Dentro da tarefa, uma propriedade MSBuild é representada por um tipo de propriedade cujo valor pode ser convertido de e para uma cadeia de caracteres. Os tipos de propriedade com suporte incluem bool, char, DateTime, Decimal, Double, , int, stringe qualquer tipo que ChangeType possa lidar.

Os itens são passados para tarefas como ITaskItem objetos. Dentro da tarefa, ItemSpec representa o valor do item e GetMetadata recupera seus metadados.

A lista de itens de um tipo de item pode ser passada como uma matriz de ITaskItem objetos. Os itens podem ser removidos de uma lista de itens em um destino usando o Remove atributo. Como os itens podem ser removidos de uma lista de itens, é possível que um tipo de item tenha zero itens. Se uma lista de itens for passada para uma tarefa, o código na tarefa deverá verificar essa possibilidade.

Ordem de avaliação de propriedade e item

Durante a fase de avaliação de um build, os arquivos importados são incorporados ao build na ordem em que aparecem. As propriedades e os itens são definidos em três passagens na seguinte ordem:

• As propriedades são definidas e modificadas na ordem em que aparecem.

• As definições de item são definidas e modificadas na ordem em que aparecem.

• Os itens são definidos e modificados na ordem em que aparecem.

Durante a fase de execução de um build, as propriedades e os itens definidos dentro dos destinos são avaliados juntos em uma única fase na ordem em que aparecem.

No entanto, esta não é a história completa. Quando uma propriedade, definição de item ou item é definida, seu valor é avaliado. O avaliador de expressão expande a cadeia de caracteres que especifica o valor. A expansão da cadeia de caracteres depende da fase de build. Aqui está uma ordem de avaliação de propriedade e item mais detalhada:

• Durante a fase de avaliação de um build:

  • As propriedades são definidas e modificadas na ordem em que aparecem. As funções de propriedade são executadas. Os valores de propriedade no formato $(PropertyName) são expandidos dentro de expressões. O valor da propriedade é definido como a expressão expandida.

  • As definições de item são definidas e modificadas na ordem em que aparecem. As funções de propriedade já foram expandidas em expressões. Os valores de metadados são definidos para as expressões expandidas.

  • Os tipos de item são definidos e modificados na ordem em que aparecem. Os valores de item no formulário @(ItemType) são expandidos. As transformações de itens também são expandidas. Funções e valores de propriedade já foram expandidos dentro de expressões. Os valores de lista de itens e metadados são definidos para as expressões expandidas.

• Durante a fase de execução de um build:

  • As propriedades e os itens definidos dentro dos destinos são avaliados juntos na ordem em que aparecem. As funções de propriedade são executadas e os valores de propriedade são expandidos dentro de expressões. Os valores de item e as transformações de item também são expandidos. Os valores de propriedade, os valores de tipo de item e os valores de metadados são definidos como as expressões expandidas.

Efeitos sutis da ordem de avaliação

Na fase de avaliação de um build, a avaliação da propriedade precede a avaliação do item. No entanto, as propriedades podem ter valores que parecem depender dos valores de item. Considere o script a seguir.

<ItemGroup>
    <KeyFile Include="KeyFile.cs">
        <Version>1.0.0.3</Version>
    </KeyFile>
</ItemGroup>
<PropertyGroup>
    <KeyFileVersion>@(KeyFile->'%(Version)')</KeyFileVersion>
</PropertyGroup>
<Target Name="AfterBuild">
    <Message Text="KeyFileVersion: $(KeyFileVersion)" />
</Target>

A execução da tarefa Mensagem exibe esta mensagem:

KeyFileVersion: 1.0.0.3

Isso ocorre porque o valor é, na verdade, a cadeia de KeyFileVersion caracteres "@(KeyFile->'%(Versão)')". As transformações de item e item não foram expandidas quando a propriedade foi definida pela primeira vez, portanto, a KeyFileVersion propriedade recebeu o valor da cadeia de caracteres não expandida.

Durante a fase de execução do build, quando ele processa a tarefa Mensagem, o MSBuild expande a cadeia de caracteres "@(KeyFile->'%(Versão)')" para produzir "1.0.0.3".

Observe que a mesma mensagem seria exibida mesmo se os grupos de propriedades e itens fossem invertidos na ordem.

Como um segundo exemplo, considere o que pode acontecer quando grupos de propriedades e itens estão localizados dentro de destinos:

<Target Name="AfterBuild">
    <PropertyGroup>
        <KeyFileVersion>@(KeyFile->'%(Version)')</KeyFileVersion>
    </PropertyGroup>
    <ItemGroup>
        <KeyFile Include="KeyFile.cs">
            <Version>1.0.0.3</Version>
        </KeyFile>
    </ItemGroup>
    <Message Text="KeyFileVersion: $(KeyFileVersion)" />
</Target>

A tarefa Mensagem exibe esta mensagem:

KeyFileVersion:

Isso ocorre porque durante a fase de execução do build, os grupos de propriedades e itens definidos dentro dos destinos são avaliados de cima para baixo ao mesmo tempo. Quando KeyFileVersion é definido, KeyFile é desconhecido. Portanto, a transformação de item se expande para uma cadeia de caracteres vazia.

Nesse caso, reverter a ordem da propriedade e dos grupos de itens restaura a mensagem original:

<Target Name="AfterBuild">
    <ItemGroup>
        <KeyFile Include="KeyFile.cs">
            <Version>1.0.0.3</Version>
        </KeyFile>
    </ItemGroup>
    <PropertyGroup>
        <KeyFileVersion>@(KeyFile->'%(Version)')</KeyFileVersion>
    </PropertyGroup>
    <Message Text="KeyFileVersion: $(KeyFileVersion)" />
</Target>

O valor é KeyFileVersion definido como "1.0.0.3" e não como "@(KeyFile->'%(Versão)')". A tarefa Mensagem exibe esta mensagem:

KeyFileVersion: 1.0.0.3

Conteúdo relacionado

• Propriedades do MSBuild
• Itens do MSBuild