Comparando itens e propriedades

As propriedades do MSBuild e os itens ambas são usados para passar informações para tarefas, para avaliar circunstâncias, e armazenam valores que podem ser referenciados em todo o arquivo de projeto.

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

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

Escalares e vetores

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

Injeção de dependência alvo

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

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

A propriedade de BuildDependsOn é normalmente usado como o argumento de um atributo de DependsOnTargets de destino, efetivamente converter a 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 a BuildDependsOn o valor BeforeBuild; CoreBuild; AfterBuild; CustomBuild.

Iniciando com o MSBuild 4,0, a inclusão de dependência alvo é substituída.Use os atributos de AfterTargets e de BeforeTargets em vez de isso.Para mais informações, consulte Ordem de compilação de destino.

Conversões entre cadeias de caracteres e listas de item

MSBuild executa conversões para e os tipos de itens e de valores de cadeia de caracteres quando necessário.Para ver como uma lista de item 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 do MSBuild:

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

o tipo de item OutputDir tem um atributo de Include com o valor “KeyFiles \; certificados \”.MSBuild analisa essa cadeia de caracteres em dois itens: KeyFiles e certificados \ \.Quando o tipo de item OutputDir é usado como o valor da propriedade de OutputDirList, converte do MSBuild ou “” aplainam o tipo de item à cadeia de caracteres ponto-e-vírgula- separada KeyFiles \ “; certificados \”.

Propriedades e itens nas tarefas

As propriedades e os itens são usados como entrada e saída para tarefas do MSBuild.Para mais informações, consulte Tarefas do MSBuild.

As propriedades são passados para tarefas como atributos.Dentro de tarefas, uma propriedade do 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 bool, char, DateTime, Decimal, Double, int, string, e qualquer tipo que ChangeType pode manipular.

Os itens são passados para tarefas como objetos de ITaskItem .Dentro de tarefas, ItemSpec representa o valor do item e GetMetadata obtém os metadados.

A lista de itens de um tipo de item pode ser passada como uma matriz de objetos de ITaskItem .Iniciando com o .NET Framework 3,5, itens podem ser removidos de uma lista de itens em um destino usando o atributo de Remove .Como os itens podem ser removidos de uma lista de itens, é possível para um tipo de item ter itens zero.Se uma lista de item é passada para uma tarefa, o código na tarefa deve verificar essa possibilidade.

Ordem de classificação de propriedade e de item

Durante a fase de avaliação de uma compilação, os arquivos importados são inseridos na compilação na ordem em que aparecem.As propriedades e os itens são definidos em três passa 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 uma compilação, as propriedades e os itens que são definidos nos destinos são avaliados juntos em uma etapa monofásica na ordem em que aparecem.

Em o entanto, isso não é o artigo completo.Quando uma propriedade, uma definição de item, ou um item são definidos, seu valor é avaliada.O avaliador de expressão expande a cadeia de caracteres especificando o valor.A expansão de cadeia de caracteres é dependente no estágio de compilação.Aqui está um ordem mais detalhado de avaliação de propriedade e de item:

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

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

  • As definições de item são definidas e modificadas na ordem em que aparecem.Funções de propriedade têm sido expandidas já 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 do item no formulário ItemType (@) são expandidos.Transformações de item são expandidas também.As funções e valores de propriedade têm sido expandidos já em 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 que são definidos nos destinos são avaliados juntos na ordem em que aparecem.Funções de propriedade são executadas e valores de propriedade são expandidos dentro de expressões.Os valores de item e as transformações de item são expandidos também.Os valores de propriedade, valores do tipo de item, e os valores de metadados são definidos para as expressões expandidas.

Efeitos sutis de ordem de classificação

Em o estágio de avaliação de uma compilação, a avaliação da propriedade antes da avaliação de item.Entretanto, as propriedades podem ter valores que parecem depender os 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 é realmente a cadeia de caracteres “@ (keyfile->'% versão) (')”.O item e as transformações de item não foram expandidos quando a propriedade foi definida primeiro, assim que a propriedade de KeyFileVersion foi atribuído o valor da cadeia de caracteres unexpanded.

Durante a fase de execução de compilação, quando ele processa a tarefa de mensagem, MSBuild expande a cadeia de caracteres “@ (keyfile->'% versão) (')” para produzir “1.0.0.3”.

Observe que a mesma mensagem apareceria mesmo se os grupos de propriedades e de item são invertidas em ordem.

Como um segundo exemplo, considere o que pode acontecer quando grupos de propriedades e de item estão localizados dentro 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 de compilação, grupos de propriedades e de item destinos são definidos em de cima para baixo avaliado ao mesmo tempo.Quando KeyFileVersion é definido, KeyFile é conhecido.Portanto, a transformação de item expande para uma cadeia de caracteres vazia.

Em esse caso, invertendo a ordem dos grupos de propriedades e de 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 é definido como “1.0.0.3” e “não @ (keyfile->'% versão) (')”.A tarefa de mensagem exibe esta mensagem:

KeyFileVersion: 1.0.0.3

Consulte também

Outros recursos

MSBuild avançados conceitos