Condições do MSBuild

Artigo
10/05/2024

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 `<`. O símbolo `>` é representado como `>`.
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 Condition elemento é uma única cadeia de caracteres e, portanto, todas as cadeias de caracteres usadas na expressão, inclusive em torno de valores de propriedade, precisam ser colocadas entre aspas simples. Espaços entre operadores são permitidos e comumente usados para legibilidade, mas não são obrigatórios.

Para usar os operadores booleanos And e Or , especifique operandos dentro do Condition valor da cadeia de caracteres do elemento, como no exemplo a seguir:

Condition="'$(Configuration)' == 'Debug' And '$(MSBuildProjectExtension)' == '.csproj'"

Você pode encadear os operadores booleanos. O operador And tem precedência maior do que Or, mas, para maior clareza, recomendamos que você use parênteses ao usar vários operadores booleanos 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

Compartilhar via