Comparar propriedades e itens

As propriedades e os 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, consulte propriedades do MSBuild.

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

Escalares e vetores

Como as propriedades 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 item.

Injeção de dependência alvo

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-o 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, fornecendo BuildDependsOn o valor BeforeBuild;CoreBuild;AfterBuild;CustomBuild.

A partir do MSBuild 4.0, a injeção de dependência de destino foi preterida. Em vez disso, use os AfterTargets atributos e BeforeTargets . Para obter mais informações, consulte Ordem de compilação 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\". 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, 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 para e de uma cadeia de caracteres. Os tipos de propriedade suportados incluem , , , , boolchar, DateTime, Decimale qualquer tipo que Double possa manipular. intstringChangeType

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 propriedades e itens

Durante a fase de avaliação de uma compilação, os arquivos importados são incorporados à compilação 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 itens 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 uma compilação, propriedades e itens que são definidos dentro de metas 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 compilação. Aqui está uma ordem de avaliação de propriedade e item mais detalhada:

• Durante a fase de avaliação de uma compilação:

  • 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 das expressões. O valor da propriedade é definido como a expressão expandida.

  • As definições de itens são definidas e modificadas na ordem em que aparecem. As funções de propriedade já foram expandidas dentro das 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 formato @(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. A lista de itens e os valores de metadados são definidos para as expressões expandidas.

• Durante a fase de execução de uma compilação:

  • 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 das expressões. Os valores e as transformações de item também são expandidos. Os valores de propriedade, valores de tipo de item e valores de metadados são definidos para as expressões expandidas.

Efeitos subtis da ordem de avaliação

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

<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 de KeyFileVersion é, na verdade, a string "@(KeyFile->'%(Version)')". 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 da compilação, quando processa a tarefa Mensagem, o MSBuild expande a cadeia de caracteres "@(KeyFile->'%(Version)')" para produzir "1.0.0.3".

Observe que a mesma mensagem apareceria mesmo se a propriedade e os grupos de itens fossem invertidos na ordem.

Como segundo exemplo, considere o que pode acontecer quando propriedades e grupos de 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 da compilação, os grupos de propriedades e itens definidos dentro dos alvos 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, inverter 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 de KeyFileVersion é definido como "1.0.0.3" e não como "@(KeyFile->'%(Version)')". A tarefa Mensagem exibe esta mensagem:

KeyFileVersion: 1.0.0.3

Conteúdo relacionado

• propriedades do MSBuild
• itens do MSBuild