Condições do MSBuild

  • Artigo

O MSBuild dá suporte a um conjunto específico de condições que podem ser aplicadas em qualquer lugar em que um atributo Condition seja permitido; consulte Elementos com suporte. A tabela a seguir explica essas condições.

Condição Descrição
'stringA' == 'stringB' Avaliará como true se stringA for igual a stringB.

Por exemplo:

Condition="'$(Configuration)'=='DEBUG'"

As aspas simples não são necessárias para cadeia de caracteres alfanuméricas simples ou valores booleanos. No entanto, as aspas são necessárias para valores vazios. Essa verificação não diferencia maiúsculas de minúsculas.
'stringA' != 'stringB' Avalia como true se stringA não for igual a stringB.

Por exemplo:

Condition="'$(Configuration)'!='DEBUG'"

As aspas simples não são necessárias para cadeia de caracteres alfanuméricas simples ou valores booleanos. No entanto, as aspas são necessárias para valores vazios. Essa verificação não diferencia maiúsculas de minúsculas.
<, >, <=, >= Avalia os valores numéricos dos operandos. Retornará true se a avaliação relacional for true. Os operandos devem ser avaliados como um número decimal ou hexadecimal ou uma versão pontilhada de quatro partes. Os números hexadecimais devem começar com 0x. Observação: no XML, os caracteres < e > devem ser escapados. O símbolo < é representado como &lt;. O símbolo > é representado como &gt;.
Exists('stringA') Avaliará como true se existir um arquivo ou pasta com o nome stringA.

Por exemplo:

Condition="!Exists('$(Folder)')"

As aspas simples não são necessárias para cadeia de caracteres alfanuméricas simples ou valores booleanos. No entanto, as aspas são necessárias para valores vazios. Essa condição não expande caracteres curinga como *.
HasTrailingSlash('stringA') Avaliará como true se a cadeia de caracteres contiver um caractere de barra invertida (\) ou de barra (/) à direita.

Por exemplo:

Condition="!HasTrailingSlash('$(OutputPath)')"

As aspas simples não são necessárias para cadeia de caracteres alfanuméricas simples ou valores booleanos. No entanto, as aspas são necessárias para valores vazios.
! Avaliará como true se o operando for avaliado como false.
And Avaliará como true se ambos os operandos forem avaliados como true.
Or Avaliará como true se pelo menos um dos operandos for avaliado como true.
() Mecanismo de agrupamento que será avaliado como true se as expressões contidas dentro forem avaliadas como true.
$if$ ( %expression% ), $else$, $endif$ Verifica se o %expression% especificado corresponde ao valor de cadeia de caracteres do parâmetro do modelo personalizado passado. Se a condição $if$ for avaliada como true, suas declarações serão executadas, caso contrário, a condição $else$ será verificada. Se a condição $else$ for true, suas declarações serão executadas, caso contrário, a condição $endif$ encerrará a avaliação da expressão.

Para obter exemplos de uso, confira Lógica de parâmetro do modelo de item/projeto do Visual Studio.

O operador And tem precedência maior que Or, mas para maior clareza, recomendamos que você use parênteses quando usar vários operadores boolianos para tornar a ordem de avaliação explícita. Se você não fizer isso, o MSBuild fornecerá o aviso MSB4130.

Você pode usar métodos de cadeia de caracteres em condições, conforme mostrado no exemplo a seguir, no qual a função TrimEnd() é usada para comparar apenas a parte relevante da cadeia de caracteres, para diferenciar entre estruturas de destino do .NET Framework e do .NET Core.

<Project Sdk="Microsoft.NET.Sdk">

    <PropertyGroup>
        <TargetFrameworks>net45;net48;netstandard2.1;netcoreapp2.1;netcoreapp3.1</TargetFrameworks>
    </PropertyGroup>

    <PropertyGroup Condition="'$(TargetFramework.TrimEnd(`0123456789`))' == 'net'">
        <!-- Properties for .NET Framework -->
    </PropertyGroup>

</Project>

Nos arquivos de projeto do MSBuild, não há nenhum tipo booliano verdadeiro. Os dados boolianos são representados em propriedades que podem estar vazias ou definidas como qualquer valor. Portanto, '$(Prop)' == 'true' significa "if Prop is true," mas '$(Prop)' != 'false' significa "if Prop is true or unset or set to something else."

A lógica booliana só é avaliada no contexto de condições. Portanto, as configurações de propriedade como <Prop2>'$(Prop1)' == 'true'</Prop> são representadas como uma cadeia de caracteres (após a expansão da variável), não avaliadas como valores boolianos.

O MSBuild implementa algumas regras de processamento especiais para facilitar o trabalho com propriedades de cadeia de caracteres que são usadas como valores boolianos. Literais boolianos são aceitos, portanto, Condition="true" e Condition="false" funcionam conforme o esperado. O MSBuild também inclui regras especiais para dar suporte ao operador de negação booliano. Portanto, se $(Prop) for 'true', !$(Prop) expandirá para !true e esse valor é comparado igual a false, como seria de esperar.

Comparando versões

Os operadores relacionais <, >, <= e >= dão suporte a versões conforme analisado por System.Version, para que você possa comparar versões que têm quatro partes numéricas entre si. Por exemplo, '1.2.3.4' < '1.10.0.0' é true.

Cuidado

System.Version comparações podem produzir resultados surpreendentes quando uma ou ambas as versões não especificam todas as quatro partes. Por exemplo, a versão 1.1 é mais antiga que a versão 1.1.0.

O MSBuild fornece funções de propriedade para comparar versões que têm um conjunto diferente de regras compatíveis com o controle de versão semântico (semver).

Expansões em condições

Dependendo da posição no arquivo de projeto, você poderá usar expansões para propriedades ($), listas de itens (@) e metadados de item (%). As expansões dependem de como o MSBuild processa arquivos de projeto.

Propriedades

Uma condição que contém uma expressão como $(SomeProperty) é avaliada e convertida no valor da propriedade. Se a condição estiver fora de um destino, a expressão será avaliada durante a avaliação do arquivo de projeto. O valor da propriedade depende da posição no arquivo de projeto depois de expandir todas as importações. Se a condição estiver em um destino, ela será avaliada quando o destino for executado, e o valor será afetado por quaisquer alterações que ocorram durante a execução da compilação.

Uma propriedade que não está definida no ponto do arquivo do projeto expandido no qual ocorre a expressão de condição é avaliada como uma cadeia de caracteres vazia, sem nenhum erro de diagnóstico ou aviso.

Listas de itens

Uma condição que contém uma @-expression como @(SomeItems) é expandida em grupos de itens no nível superior e em destinos.

Os itens podem depender de qualquer propriedade e podem depender de itens que já estão definidos em sequência.

O motivo é que o MSBuild processa arquivos de projeto em várias passagens. A aprovação de avaliação do item ocorre após a avaliação da propriedade inicial e a aprovação de expansão de importação. Portanto, as @-expressões são permitidas em qualquer condição que seja avaliada depois que os itens começarem a ser definidos. Ou seja, em itens, grupos de itens e em destinos.

Metadados

Uma condição que contém uma expressão de metadados como %(ItemMetadata) é expandida nos mesmos contextos que listas de itens, ou seja, em grupos de itens no nível superior e em destinos. No entanto, a expansão pode ter um comportamento diferente em um grupo de itens, dependendo se o grupo de itens está fora de um destino ou dentro de um destino. Além disso, das várias formas de expressões de metadados, %(ItemName.MetadataName), %(JustTheMetadataName) e @(ItemName->'%(MetadataName)'), somente a transformação de item (a última) é permitida fora de um destino. O valor de uma %-expressão em um destino é avaliado em tempo de execução e depende de qualquer alteração de estado durante a execução de destino. A execução do destino e do valor de qualquer %-expressão contida nele também depende do envio em lote do destino e também pode disparar o envio em lote. Confira Envio em lote do MSBuild.

Elementos suportados

Os elementos a seguir dão suporte para o atributo Condition:

  • Importar
  • ImportGroup
  • Item
  • ItemDefinitionGroup
  • ItemGroup
  • ItemMetadata
  • OnError
  • Saída
  • Propriedade
  • PropertyGroup
  • Destino
  • Tarefa
  • UsingTask
  • Quando

Confira também