Funções de propriedade

As funções de propriedade são chamadas para métodos do .NET que aparecem nas definições de propriedade do MSBuild. Normalmente, você as usa para construir definições de propriedade que exigem uma lógica mais complexa.

Ao contrário das tarefas, as funções de propriedade podem ser utilizadas fora dos alvos. As funções de propriedade são avaliadas sempre que as propriedades ou itens são expandidos. Portanto, para propriedades e itens fora de qualquer destino, as funções de propriedade são avaliadas antes de qualquer execução de destino. Para grupos de propriedades e grupos de itens dentro de alvos, as funções de propriedades são avaliadas quando o alvo é executado.

Sem usar tarefas do MSBuild, você pode ler o tempo do sistema, comparar cadeias de caracteres, corresponder a expressões regulares e executar outras ações no script de build. MSBuild tenta converter string em número e número em string e realizar outras conversões conforme necessário.

Valores de cadeia de caracteres retornados de funções de propriedade tem caracteres especiais de escape. Se você quiser que o valor seja tratado como se fosse colocado diretamente no arquivo do projeto, use $([MSBuild]::Unescape()) para desfazer o escape dos caracteres especiais.

Sintaxe da função de propriedade

Há três tipos de funções de propriedade; cada tipo tem uma sintaxe diferente:

• Funções de propriedade de cadeia de caracteres (instância)
• Funções de propriedade estática
• Funções de propriedade MSBuild

Funções de propriedade de cadeia de caracteres

Todos os valores de propriedade de build são apenas valores de cadeia de caracteres. Você pode usar métodos de cadeia (instância) para operar em qualquer valor de propriedade. Por exemplo, você pode extrair o nome da unidade de disco (os três primeiros caracteres) de uma propriedade de build que representa um caminho completo, utilizando este código:

$(ProjectOutputFolder.Substring(0,3))

Funções de propriedade estática

No script de build, você pode acessar as propriedades estáticas e os métodos de muitas classes do sistema. Para obter o valor de uma propriedade estática, use a sintaxe a seguir, onde Class está o nome da classe do sistema e Property é o nome da propriedade.

$([Class]::Property)

Por exemplo, você pode usar o código a seguir para definir uma propriedade de build para a data e hora atuais.

<Today>$([System.DateTime]::Now)</Today>

Para chamar um método estático, use a seguinte sintaxe, onde Class está o nome da classe do sistema, Method é o nome do método e (Parameters) é a lista de parâmetros para o método:

$([Class]::Method(Parameters))

Por exemplo, para definir uma propriedade de build para um novo GUID, você pode usar este script:

<NewGuid>$([System.Guid]::NewGuid())</NewGuid>

Para métodos sobrecarregados, o MSBuild tenta encontrar um método com parâmetros correspondentes.

No MSBuild 17.14 e posterior, você pode usar a sintaxe out _ de parâmetro para especificar um out parâmetro. Consulte parâmetros de referência. O valor do out parâmetro é ignorado. Por exemplo:

<IsInteger>$([System.Int32]::TryParse("123", out _))</IsInteger>

A propriedade IsInteger será true se a entrada for analisada com êxito como um inteiro, mas o valor analisado for ignorado.

Em funções de propriedade estática, você pode usar qualquer método estático público ou propriedade definida no .NET Standard 2.0 para estas classes do sistema:

• System.Byte
• System.Char
• System.Convert
• System.DateTime
• System.DateTimeOffset (disponível no MSBuild 17.3 e superior)
• System.Decimal
• System.Double
• System.Enum
• System.Guid
• System.Int16
• System.Int32
• System.Int64
• System.IO.Path
• System.Math
• System.Runtime.InteropServices.OSPlatform
• System.Runtime.InteropServices.RuntimeInformation
• System.UInt16
• System.UInt32
• System.UInt64
• System.SByte
• System.Single
• System.String
• System.StringComparer
• System.TimeSpan
• System.Text.RegularExpressions.Regex
• System.UriBuilder
• System.Version
• Microsoft.Build.Utilities.ToolLocationHelper

Além disso, você pode usar os seguintes métodos estáticos e propriedades:

• System.Environment::CommandLine
• System.Environment::ExpandEnvironmentVariables
• System.Environment::GetEnvironmentVariable
• System.Environment::GetEnvironmentVariables
• System.Environment::GetFolderPath
• System.Environment::GetLogicalDrives
• System.Environment::Is64BitOperatingSystem
• System.Environment::Is64BitProcess
• System.Environment::MachineName
• System.Environment::NewLine
• System.Environment::OSVersion
• System.Environment::ProcessorCount
• System.Environment::StackTrace
• System.Environment::SystemDirectory
• System.Environment::SystemPageSize
• System.Environment::TickCount
• System.Environment::UserDomainName
• System.Environment::UserInteractive
• System.Environment::UserName
• System.Environment::Version
• System.Environment::WorkingSet
• System.IO.Directory::GetDirectories
• System.IO.Directory::GetFiles
• System.IO.Directory::GetLastAccessTime
• System.IO.Directory::GetLastWriteTime
• System.IO.Directory::GetParent
• System.IO.File::Exists
• System.IO.File::GetAttributes
• System.IO.File::GetCreationTime
• System.IO.File::GetLastAccessTime
• System.IO.File::GetLastWriteTime
• System.IO.File::ReadAllText
• System.Globalization.CultureInfo::GetCultureInfo
• System.Globalization.CultureInfo::new
• System.Globalization.CultureInfo::CurrentUICulture

<IsWindows>$([System.OperatingSystem]::IsWindows())</IsWindows>

Chamar métodos de instância em propriedades estáticas

Se você acessar uma propriedade estática que retorna uma instância de objeto, poderá invocar os métodos de instância desse objeto. Para invocar um método de instância, use a seguinte sintaxe, onde Class está o nome da classe do sistema, Property é o nome da propriedade, Method é o nome do método e (Parameters) é a lista de parâmetros para o método:

$([Class]::Property.Method(Parameters))

O nome da classe deve ser totalmente qualificado com o namespace.

Por exemplo, você pode usar o código a seguir para definir uma propriedade de build para a data atual hoje.

<Today>$([System.DateTime]::Now.ToString('yyyy.MM.dd'))</Today>

Funções de propriedade MSBuild

Vários métodos estáticos em seu build podem ser acessados para fornecer suporte a operações aritméticas, operações lógicas bit a bit e caracteres de escape. Você acessa esses métodos usando a sintaxe a seguir, onde Method está o nome do método e (Parameters) é a lista de parâmetros para o método.

$([MSBuild]::Method(Parameters))

Por exemplo, para adicionar duas propriedades que têm valores numéricos, use o código a seguir.

$([MSBuild]::Add($(NumberOne), $(NumberTwo)))

Aqui está uma lista de funções de propriedade do MSBuild:

Funções de propriedade aninhadas

Você pode combinar funções de propriedade para formar funções mais complexas, como mostra o exemplo a seguir:

$([MSBuild]::BitwiseAnd(32, $([System.IO.File]::GetAttributes(tempFile))))

Este exemplo retorna o valor do FileAttributes. Bit Archive (32 ou 0) do arquivo fornecido pelo caminho tempFile. Observe que os valores de dados enumerados não podem aparecer por nome em alguns contextos. No exemplo anterior, o valor numérico (32) deve ser usado. Em outros casos, dependendo das expectativas do método chamado, o valor dos dados de enumeração deve ser usado. No exemplo a seguir, o valor de enumeração RegexOptions. ECMAScript deve ser usado porque um valor numérico não pode ser convertido como este método espera.

<PropertyGroup>
    <GitVersionHeightWithOffset>$([System.Text.RegularExpressions.Regex]::Replace("$(PrereleaseVersion)", "^.*?(\d+)$", "$1", "System.Text.RegularExpressions.RegexOptions.ECMAScript"))</GitVersionHeightWithOffset>
</PropertyGroup>

Metadados também podem aparecer em funções de propriedade aninhadas. Para obter mais informações, consulte Envio em lote.

MSBuild DoesTaskHostExist

A função de propriedade DoesTaskHostExist no MSBuild retorna se um host de tarefa está atualmente instalado para os valores especificados de tempo de execução e arquitetura.

Essa função de propriedade tem a seguinte sintaxe:

$([MSBuild]::DoesTaskHostExist(string theRuntime, string theArchitecture))

EnsureTrailingSlash do MSBuild

A função de propriedade EnsureTrailingSlash no MSBuild adicionará uma barra à direita se não houver.

Essa função de propriedade tem a seguinte sintaxe:

$([MSBuild]::EnsureTrailingSlash('$(PathProperty)'))

MSBuild GetDirectoryNameOfFileAbove

A função de propriedade MSBuild GetDirectoryNameOfFileAbove pesquisa em direção ascendente por um diretório que contém o arquivo especificado, começando no diretório especificado e incluindo-o. Ele retorna o caminho completo do diretório mais próximo que contém o arquivo se ele for encontrado, caso contrário, uma cadeia de caracteres vazia.

Essa função de propriedade tem a seguinte sintaxe:

$([MSBuild]::GetDirectoryNameOfFileAbove(string startingDirectory, string fileName))

Este exemplo mostra como importar o arquivo EnlistmentInfo.props mais próximo dentro ou acima da pasta atual, somente se uma correspondência for encontrada:

<Import Project="$([MSBuild]::GetDirectoryNameOfFileAbove($(MSBuildThisFileDirectory), EnlistmentInfo.props))\EnlistmentInfo.props" Condition=" '$([MSBuild]::GetDirectoryNameOfFileAbove($(MSBuildThisFileDirectory), EnlistmentInfo.props))' != '' " />

Este exemplo pode ser escrito de forma mais concisa usando a GetPathOfFileAbove função em vez disso:

<Import Project="$([MSBuild]::GetPathOfFileAbove(EnlistmentInfo.props))" Condition=" '$([MSBuild]::GetPathOfFileAbove(EnlistmentInfo.props))' != '' " />

GetPathOfFileAbove do MSBuild

A função de propriedade MSBuild GetPathOfFileAbove pesquisa em direção ascendente por um diretório que contém o arquivo especificado, começando no diretório especificado e incluindo-o. Ele retorna o caminho completo do arquivo correspondente mais próximo se for encontrado, caso contrário, uma cadeia de caracteres vazia.

Essa função de propriedade tem a seguinte sintaxe:

$([MSBuild]::GetPathOfFileAbove(string file, [string startingDirectory]))

onde file está o nome do arquivo a ser pesquisado e startingDirectory é um diretório opcional para iniciar a pesquisa. Por padrão, a pesquisa é iniciada no próprio diretório do arquivo atual.

Este exemplo mostra como importar um arquivo chamado dir.props dentro ou acima do diretório atual, somente se uma correspondência for encontrada:

<Import Project="$([MSBuild]::GetPathOfFileAbove(dir.props))" Condition=" '$([MSBuild]::GetPathOfFileAbove(dir.props))' != '' " />

que é funcionalmente equivalente a

<Import Project="$([MSBuild]::GetDirectoryNameOfFileAbove($(MSBuildThisFileDirectory), dir.props))\dir.props" Condition=" '$([MSBuild]::GetDirectoryNameOfFileAbove($(MSBuildThisFileDirectory), dir.props))' != '' " />

No entanto, às vezes, você precisa iniciar a pesquisa no diretório pai para evitar a correspondência com o arquivo atual. Este exemplo mostra como um arquivo Directory.Build.props pode importar o arquivo Directory.Build.props mais próximo em um nível estritamente mais alto da árvore, sem importar-se recursivamente:

<Import Project="$([MSBuild]::GetPathOfFileAbove('Directory.Build.props', '$(MSBuildThisFileDirectory)../'))" />

que é funcionalmente equivalente a

<Import Project="$([MSBuild]::GetDirectoryNameOfFileAbove('$(MSBuildThisFileDirectory)../', 'Directory.Build.props'))/Directory.Build.props" />

MSBuild GetRegistryValue

A função de propriedade MSBuild GetRegistryValue retorna o valor de uma chave do Registro. Essa função usa dois argumentos, o nome da chave e o nome do valor e retorna o valor do registro. Se você não especificar um nome de valor, o valor padrão será retornado.

Os exemplos a seguir mostram como essa função é usada:

$([MSBuild]::GetRegistryValue(`HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\10.0\Debugger`, ``))                                  // default value
$([MSBuild]::GetRegistryValue(`HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\10.0\Debugger`, `SymbolCacheDir`))
$([MSBuild]::GetRegistryValue(`HKEY_LOCAL_MACHINE\SOFTWARE\(SampleName)`, `(SampleValue)`))             // parens in name and value

MSBuild GetRegistryValueFromView

A função de propriedade GetRegistryValueFromView do MSBuild obtém os dados de registro do sistema, dados a chave do registro, o valor e uma ou mais exibições de registro solicitada. A chave e o valor são pesquisados em cada exibição do registro em ordem até serem encontrados.

A sintaxe dessa função de propriedade é:

[MSBuild]::GetRegistryValueFromView(string keyName, string valueName, object defaultValue, params object[] views)

O sistema operacional Windows de 64 bits mantém uma chave do RegistroHKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node que apresenta uma visão de RegistroHKEY_LOCAL_MACHINE\SOFTWARE para aplicativos de 32 bits.

Por padrão, um aplicativo de 32 bits em execução no WOW64 acessa a visualização do registro de 32 bits e um aplicativo de 64 bits acessa a visualização do registro de 64 bits.

As seguintes exibições de registro estão disponíveis:

A seguir, é mostrado um exemplo.

$([MSBuild]::GetRegistryValueFromView('HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Microsoft SDKs\Silverlight\v3.0\ReferenceAssemblies', 'SLRuntimeInstallPath', null, RegistryView.Registry64, RegistryView.Registry32))

O código anterior obtém os dados de SLRuntimeInstallPath da chave ReferenceAssemblies, procurando primeiro na exibição do Registro de 64 bits e depois na exibição do Registro de 32 bits.

MSBuild MakeRelative

A função de propriedade MakeRelative do MSBuild retorna o caminho relativo do segundo caminho relativo ao primeiro caminho. Cada caminho pode ser um arquivo ou pasta.

Essa função de propriedade tem a seguinte sintaxe:

$([MSBuild]::MakeRelative($(FileOrFolderPath1), $(FileOrFolderPath2)))

O código a seguir é um exemplo dessa sintaxe.

<PropertyGroup>
    <Path1>c:\users\</Path1>
    <Path2>c:\users\username\</Path2>
</PropertyGroup>

<Target Name = "Go">
    <Message Text ="$([MSBuild]::MakeRelative($(Path1), $(Path2)))" />
    <Message Text ="$([MSBuild]::MakeRelative($(Path2), $(Path1)))" />
</Target>

<!--
Output:
   username\
   ..\
-->

MSBuild StableStringHash

A função de propriedade MSBuild StableStringHash aceita um argumento de cadeia de caracteres e retorna um código hash que é garantido como estável, o que significa que o mesmo código sempre é retornado para a mesma entrada de cadeia de caracteres. O hash retornado é o mesmo, independentemente de o MSBuild ou dotnet build ser usado e ser estável em toda a arquitetura de plataforma, diferentemente do método GetHashCode.NET. Não é garantido que ele esteja estável em diferentes versões do MSBuild.

Essa função está disponível no MSBuild 16.9.0 ou posterior.

O exemplo a seguir mostra como essa função é usada.

<Project>
   <PropertyGroup>
      <MyHash>$([MSBuild]::StableStringHash("test1"))</MyHash>
   </PropertyGroup>

   <Target Name="WriteHash" AfterTargets="Build">
      <Message Text="Hash: $(MyHash)"/>
   </Target>
</Project>

Com o MSBuild versão 17.10 e posterior, essa função aceita o segundo argumento opcional solicitando que o algoritmo de hash seja usado:

<Project>
   <PropertyGroup>
      <MyHash>$([MSBuild]::StableStringHash("test1", "Sha256"))</MyHash>
   </PropertyGroup>

   <Target Name="WriteHash" AfterTargets="Build">
      <Message Text="Hash: $(MyHash)"/>
   </Target>
</Project>

O segundo argumento não diferencia maiúsculas de minúsculas e atualmente dá suporte aos seguintes valores:

• Herdado - Mantém o mesmo comportamento de chamar a função sem o segundo argumento. Retorna um inteiro de 32 bits assinado com propriedades semelhantes à string.GetHashCode.
• Fnv1a32bit – Retorna um número inteiro assinado de 32 bits que representa um hash Fowler–Noll-Vo da versão '1a' da string fornecida.
• Fnv1a64bit - Retorna um inteiro de 64 bits assinado que representa um hash Fowler-Noll-Vo da versão '1a' do hash da string fornecida.
• Sha256 – Retorna uma cadeia de caracteres hexáxe não prefixada que representa um hash SHA256 da cadeia de caracteres fornecida.

MSBuild ValueOrDefault

A função de propriedade MSBuild ValueOrDefault retorna o primeiro argumento, a menos que seja nulo ou vazio. Se o primeiro argumento for nulo ou vazio, a função retornará o segundo argumento.

O exemplo a seguir mostra como essa função é usada.

<Project>

    <PropertyGroup>
        <Value1>$([MSBuild]::ValueOrDefault('$(UndefinedValue)', 'a'))</Value1>
        <Value2>$([MSBuild]::ValueOrDefault('b', '$(Value1)'))</Value2>
    </PropertyGroup>

    <Target Name="MyTarget">
        <Message Text="Value1 = $(Value1)" />
        <Message Text="Value2 = $(Value2)" />
    </Target>
</Project>

<!--
Output:
  Value1 = a
  Value2 = b
-->

Funções TargetFramework e TargetPlatform do MSBuild

O MSBuild 16.7 e superior definem várias funções para lidar com as propriedades TargetFramework e TargetPlatform.

O versionPartCount parâmetro de GetTargetFrameworkVersion e GetTargetPlatformVersion tem um valor padrão de 2.

O exemplo a seguir mostra como essas funções são usadas.

<Project>

    <PropertyGroup>
        <Value1>$([MSBuild]::GetTargetFrameworkIdentifier('net5.0-windows7.0'))</Value1>
        <Value2>$([MSBuild]::GetTargetFrameworkVersion('net5.0-windows7.0'))</Value2>
        <Value3>$([MSBuild]::GetTargetPlatformIdentifier('net5.0-windows7.0'))</Value3>
        <Value4>$([MSBuild]::GetTargetPlatformVersion('net5.0-windows7.0'))</Value4>
        <Value5>$([MSBuild]::IsTargetFrameworkCompatible('net5.0-windows', 'net5.0'))</Value5>
        <Value6>$([MSBuild]::IsTargetFrameworkCompatible('net5.0', 'net6.0'))</Value6>
        <Value7>$([MSBuild]::IsTargetFrameworkCompatible('net5.0', 'net8.0'))</Value7>
        <Value8>$([MSBuild]::IsTargetFrameworkCompatible('net8.0', 'net6.0'))</Value8>
    </PropertyGroup>

    <Target Name="MyTarget">
        <Message Text="Value1 = $(Value1)" />
        <Message Text="Value2 = $(Value2)" />
        <Message Text="Value3 = $(Value3)" />
        <Message Text="Value4 = $(Value4)" />
        <Message Text="Value5 = $(Value5)" />
        <Message Text="Value6 = $(Value6)" />
        <Message Text="Value7 = $(Value7)" />
        <Message Text="Value8 = $(Value8)" />
    </Target>
</Project>

Value1 = .NETCoreApp
Value2 = 5.0
Value3 = windows
Value4 = 7.0
Value5 = True
Value6 = False
Value7 = False
Value8 = True

Funções de comparação de versão do MSBuild

O MSBuild 16.5 e superior definem várias funções para comparar cadeias de caracteres que representam versões.

Nesses métodos, as versões são analisadas como System.Version, com as seguintes exceções:

• Os caracteres iniciais v ou V são ignorados, o que permite a comparação com $(TargetFrameworkVersion).

• Tudo, desde o primeiro '-' ou '+' até o final da cadeia de caracteres de versão é ignorado. Isso permite passar versões semânticas (semver), embora a ordem não seja a mesma que a semver. Em vez disso, especificadores de pré-lançamento e metadados de build não têm nenhum peso de classificação. Isso pode ser útil, por exemplo, para ativar um recurso >= x.y e fazê-lo entrar em funcionamento em x.y.z-pre.

• Partes não especificadas são iguais a partes de valor zero. (x == x.0 == x.0.0 == x.0.0.0).

• O espaço em branco não é permitido em componentes inteiros.

• A versão principal só é válida (3 é igual a 3.0.0.0)

• + não é permitido como sinal positivo nos componentes inteiros (é tratado como metadados de semver e ignorado)

Funções de condição do MSBuild

As funções Exists e HasTrailingSlash não são funções de propriedade. Eles estão disponíveis para uso com o Condition atributo. Confira Condições do MSBuild.

Conteúdo relacionado

• Propriedades do MSBuild

• visão geral do MSBuild