Comparando itens e Propriedades
Itens e propriedades do MSBuild são usados para passar informações para tarefas, avaliar condições e armazenar os valores que podem ser referenciados em todo o arquivo de projeto.
As propriedades são pares nome-valor. Para obter mais informações, consulte Propriedadesdo MSBuild.
Os itens são objetos que representam os arquivos normalmente. Coleções de metadados podem ter associados a objetos de item. Metadados são pares nome-valor. Para obter mais informações, consulte Itens do MSBuild.
Escalares e vetores
Como propriedades do MSBuild são pares nome / valor que têm apenas um valor de seqüência de caracteres, geralmente são descritos como escalares. Como os tipos de item MSBuild são listas de itens, geralmente são descritos como vetor. Entretanto, na prática, propriedades podem representar vários valores e tipos de item podem ter zero ou um de itens.
Injeção de dependência de destino
Para ver como propriedades podem representar vários valores, considere a possibilidade de um padrão de uso comum para adicionar um destino para uma lista de destinos a ser criado. Esta 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>
O BuildDependsOn propriedade normalmente é usada como argumento de um destino DependsOnTargets atributo, efetivamente, convertê-lo para uma lista de item. Esta propriedade pode ser substituída para adicionar um destino ou para alterar a ordem de execução de destino. Por exemplo,
<PropertyGroup>
<BuildDependsOn>
$(BuildDependsOn);
CustomBuild;
</BuildDependsOn>
</PropertyGroup>
Adiciona o destino de CustomBuild à lista de destino, dando BuildDependsOn o valor BeforeBuild;CoreBuild;AfterBuild;CustomBuild.
Começando com o MSBuild 4.0, injeção de dependência de destino está obsoleto. Use o RunAfterTargets e RunBeforeTargets atributos em vez disso. Para obter mais informações, consulte Ordem de compilação de destino.
Conversões entre cadeias de caracteres e listas de itens
MSBuild realiza conversões entre tipos de itens e valores de string, conforme necessário. Para ver como uma lista de itens pode se tornar um valor de seqüência de caracteres, considere o que acontece quando um tipo de item é usado como o valor de uma propriedade do MSBuild:
<ItemGroup>
<OutputDir Include="KeyFiles\;Certificates\" />
</ItemGroup>
<PropertyGroup>
<OutputDirList>@(OutputDir)</OutputDirList>
</PropertyGroup>
O tipo de item OutputDir tem um atributo deInclude com o valor "KeyFiles\;Certificates\ ". MSBuild analisa a essa seqüência 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 para a seqüência de caracteres separada por ponto-e-vírgula "KeyFiles\;Certificates\ ".
Propriedades e itens de tarefas
Propriedades e os itens são usados como entradas e saídas para tarefas do MSBuild. Para obter mais informações, consulte Tarefas do MSBuild.
Propriedades são passadas para tarefas como atributos. Dentro da tarefa, uma propriedade do MSBuild é representada por um tipo de propriedade cujo valor pode ser convertido em uma seqüência de caracteres. Os tipos de propriedade suportados incluem bool, char, DateTime, Decimal, Double, int, string, e qualquer tipo que ChangeType pode manipular.
Itens são passados para tarefas como ITaskItem objetos. Dentro da tarefa, ItemSpec representa o valor do item e GetMetadata recupera metadados.
A lista de itens de um tipo de item pode ser passada como uma matriz de ITaskItem objetos. Começando com o.NET Framework 3.5, itens pode ser removido de uma lista de itens em um destino usando o Remove atributo. Porque os itens podem ser removidos de uma lista de itens, é possível para um tipo de item ter zero itens. Se uma lista de itens é passada para uma tarefa, o código da tarefa deve verificar essa possibilidade.
Propriedade e a ordem de avaliação do Item
Durante a fase de avaliação de uma compilação, os arquivos importados são incorporados a compilação na ordem em que aparecem. Propriedades e os itens são definidos em três passos na seguinte ordem:
Propriedades são definidas e modificadas na ordem em que aparecem.
Definições de item são definidas e modificadas na ordem em que aparecem.
Itens são definidos e modificados na ordem em que aparecem.
Durante a fase de execução de uma compilação, propriedades e os itens que foram definidos em destinos são avaliados juntos em uma única fase na ordem em que aparecem.
No entanto, não é a história completa. Quando uma propriedade, a definição de item ou o item é definida, seu valor é avaliado. O avaliador da expressão expande a seqüência de caracteres que especifica o valor. A expansão da cadeia de caracteres depende da fase de criação. Aqui está uma ordem de avaliação de propriedade e o item mais detalhada:
Durante a fase de avaliação de uma compilação:
Propriedades são definidas e modificadas na ordem em que aparecem. Funções de propriedade são executadas. Os valores de propriedade no $(PropertyName) do formulário são expandidos dentro de expressões. O valor da propriedade é definido como a expressão expandido.
Definições de item são definidas e modificadas na ordem em que aparecem. Funções de propriedade já foram expandidas em expressões. Os valores de metadados são definidos como as expressões expandidas.
Tipos de item são definidos e modificados na ordem em que aparecem. Os valores do item no @(ItemType) do formulário são expandidos. Item transformações também são expandidas. Valores e funções de propriedade já foi expandidos em expressões. Os valores de lista e os metadados de item são definidos como as expressões expandidas.
Durante a fase de execução de uma compilação:
- Propriedades e os itens que foram definidos em destinos são avaliados juntos na ordem em que aparecem. Funções de propriedade são executadas e os valores de propriedade são expandidos dentro de expressões. Os valores de item e item transformações também são expandidas. Os valores de propriedade, os valores de tipo de item e valores de metadados são definidos como as expressões expandidas.
Efeitos sutis na ordem de avaliação
Na fase de avaliação de uma compilação, a avaliação da propriedade precede a avaliação de item. No entanto, as propriedades podem ter valores que aparecem dependem de valores de 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>
Executar a tarefa de mensagem exibe esta mensagem:
KeyFileVersion: 1.0.0.3
Isso ocorre porque o valor de KeyFileVersion é na verdade, a seqüência "@ (KeyFile - > '(versão) %')". Transformações de item e o item não foram expandidas quando a propriedade foi definida pela primeira vez, portanto, o KeyFileVersion propriedade foi atribuída o valor da seqüência de caracteres não-expandida.
Durante a fase de execução da compilação, quando ele processa a tarefa de mensagem, o MSBuild expande a seqüência de caracteres "@ (KeyFile - > '(versão) %')" para produzir "1.0.0.3".
Observe que a mesma mensagem seria exibida, mesmo se os grupos de propriedade e o item revertidos na ordem.
Como um segundo exemplo, considere o que pode acontecer quando a propriedade e o item grupos 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 de mensagem exibe esta mensagem:
KeyFileVersion:
Isso ocorre porque durante a fase de execução da compilação, os grupos de propriedade e o item definidos em destinos são avaliados cima para baixo, ao mesmo tempo. Quando KeyFileVersion for definido, KeyFile é desconhecido. Portanto, a transformação de item expande para uma seqüência vazia.
Nesse caso, invertendo a ordem dos grupos de propriedade e o item 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 é definida como "1.0.0.3" e não para "@ (KeyFile - > '(versão) %')". A tarefa de mensagem exibe esta mensagem:
KeyFileVersion: 1.0.0.3