Funções de propriedade

Funções de propriedade são chamadas para métodos .NET que aparecem em definições de propriedade MSBuild. Normalmente, você os 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 usadas fora dos alvos. As funções de propriedade são avaliadas sempre que as propriedades ou itens são expandidos. Assim, para propriedades e itens fora de quaisquer destinos, as funções de propriedade são avaliadas antes de qualquer destino ser executado. Para grupos de propriedades e grupos de itens dentro de destinos, as funções de propriedade são avaliadas quando um destino é executado.

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

Os valores de cadeia de caracteres retornados de funções de propriedade têm caracteres especiais escapados. Se você quiser que o valor seja tratado como se tivesse sido colocado diretamente no arquivo de projeto, use $([MSBuild]::Unescape()) para escapar dos caracteres especiais.

Sintaxe da função Propriedade

Existem três tipos de funções de propriedade; Cada tipo tem uma sintaxe diferente:

• Funções de propriedades de instância de String
• Funções de propriedade estática
• Funções de propriedade MSBuild

Funções de propriedades de String

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

$(ProjectOutputFolder.Substring(0,3))

Funções de propriedade estática

Em seu script de construção, você pode acessar as propriedades estáticas e métodos de muitas classes do sistema. Para obter o valor de uma propriedade estática, use a sintaxe a seguir, onde Class é 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 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 é 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 build para um novo GUID, você pode usar este script:

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

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

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

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

A propriedade IsInteger é true se a entrada for parseada com sucesso como um inteiro, mas o valor parseado é 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 de sistema:

• System.Byte
• System.Char
• System.Converter
• System.DateTime
• System.DateTimeOffset (Disponível no MSBuild 17.3 e superior)
• System.Decimal
• Sistema.Duplo
• System.Enum
• System.Guid
• Sistema.Int16
• Sistema.Int32
• Sistema.Int64
• System.IO.Path
• System.Matemática
• System.Runtime.InteropServices.OSPlatform
• System.Runtime.InteropServices.RuntimeInformation
• Sistema.UInt16
• Sistema.UInt32
• System.UInt64
• System.SByte
• Sistema.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::Linha de Comando
• System.Environment::ExpandEnvironmentVariables (Expande as variáveis de ambiente)
• 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::P rocessorCount
• System.Environment::StackTrace
• System.Environment::SystemDirectory
• System.Environment::SystemPageSize
• System.Environment::TickCount
• System.Environment::UserDomainName
• System.Environment::UserInteractive
• System.Environment::Nome de Usuário
• System.Environment::Versão
• 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::Existe
• 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::novo
• 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 é 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 compilação para a data atual.

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

Funções de propriedade MSBuild

Vários métodos estáticos no seu processo de build podem ser acedidos para fornecer suporte a aritmética, lógica bit a bit e caracteres de escape. Você acessa esses métodos usando a sintaxe a seguir, onde Method é 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 MSBuild:

Funções de propriedade aninhada

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 de .FileAttributes Archive bit (32 ou 0) do arquivo dado pelo caminho tempFile. Observe que os valores de dados enumerados não podem aparecer pelo nome em alguns contextos. No exemplo anterior, em vez disso, deve ser usado o valor numérico (32). Em outros casos, dependendo das expectativas do método chamado, o valor de dados enum deve ser usado. No exemplo a seguir, o valor enum 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>

Os metadados também podem aparecer em funções de propriedade aninhadas. Para obter mais informações, consulte Batching.

MSBuild DoesTaskHostExist

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

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

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

MSBuild EnsureTrailingSlash

A função de propriedade EnsureTrailingSlash no MSBuild adiciona uma barra final, se ainda não existir.

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

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

MSBuild GetDirectoryNameOfFileAbove

A função de propriedade MSBuild GetDirectoryNameOfFileAbove procura para cima um diretório que contém o arquivo especificado, começando em (e incluindo) o diretório especificado. 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.

Esta 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:

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

MSBuild GetPathOfFileAbove

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

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

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

onde file é 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 é preciso iniciar a pesquisa no diretório pai, para evitar correspondência com o ficheiro 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 recursivamente a si mesmo:

<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. Esta 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 MSBuild GetRegistryValueFromView obtém dados do Registro do sistema dada a chave do Registro, o valor e uma ou mais exibições do Registro ordenadas. A chave e o valor são pesquisados em cada vista do registro, em ordem, até serem encontrados.

A sintaxe para esta função de propriedade é:

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

O sistema operativo Windows de 64 bits mantém uma chave de registo HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node que apresenta uma vista de registo HKEY_LOCAL_MACHINE\SOFTWARE para aplicações de 32 bits.

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

Estão disponíveis as seguintes vistas de registo:

Segue-se 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, pesquisando primeiro na visualização do registo de 64 bits e, em seguida, na exibição do registo de 32 bits.

MSBuild MakeRelative

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

Esta 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 para ser 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 ser MSBuild ou dotnet build usado, e é estável em toda a arquitetura da plataforma, ao contrário do método GetHashCode.NET. Não é garantido que seja estável em diferentes versões do MSBuild.

Esta 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, esta função aceita o segundo argumento, opcional, solicitando o algoritmo de hash a ser 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 suporta os seguintes valores:

• Legacy - mantém o mesmo comportamento que chamar a função sem o segundo argumento. Retorna um inteiro assinado de 32 bits com propriedades semelhantes a string.GetHashCode.
• Fnv1a32bit - Devolve um inteiro de 32 bits assinado que representa um hash Fowler–Noll–Vo do hash da versão '1a' da cadeia de caracteres fornecida.
• Fnv1a64bit - Retorna um inteiro de 64 bits assinado representando um hash Fowler–Noll–Vo da versão '1a' da string fornecida.
• Sha256 - Retorna uma cadeia de caracteres hexadecimal 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 MSBuild TargetFramework e TargetPlatform

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

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:

• 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 da versão, é ignorado. Isso permite a passagem em versões semânticas (semver), embora a ordem não seja a mesma que semver. Em vez disso, os especificadores de pré-lançamento e os metadados de compilação não têm qualquer peso de classificação. Isso pode ser útil, por exemplo, para ativar uma funcionalidade para >= x.y e fazê-la entrar em efeito em x.y.z-pre.

• As partes não especificadas são iguais às peças de valor zero. (x == x.0 == x.0.0 == x.0.0.0)

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

• Apenas a versão principal é válida (3 é igual a 3.0.0.0)

• + não é permitido como sinal positivo em componentes inteiros (é tratado como metadados 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. Consulte condições do MSBuild.

Conteúdo relacionado

• propriedades do MSBuild

• Visão geral do MSBuild