Funciones relacionadas con propiedades

Las funciones de propiedad son llamadas a métodos de .NET que aparecen en las definiciones de propiedades de MSBuild. Normalmente, se usan para construir definiciones de propiedad que requieren lógica más compleja.

A diferencia de las tareas, las funciones de propiedad se pueden usar fuera de los objetivos. Las funciones de propiedad se evalúan cada vez que se expanden las propiedades o los elementos. Por lo tanto, para las propiedades y elementos que no están en ningún destino, las funciones de propiedad se evalúan antes de que se ejecute cualquier destino. En el caso de los grupos de propiedades y los grupos de elementos dentro de los destinos, las funciones de propiedad se ejecutan cuando se evalúa el destino.

Sin usar tareas de MSBuild, puede leer la hora del sistema, comparar cadenas, hacer coincidir expresiones regulares y realizar otras acciones en el script de compilación. MSBuild intenta convertir la cadena en número y número en cadena y realizar otras conversiones según sea necesario.

Los valores de cadena devueltos por las funciones de propiedad tienen caracteres especiales con secuencia de escape. Si quiere que el valor se considere como si se hubiese implementado directamente en el archivo del proyecto, use $([MSBuild]::Unescape()) para quitar las secuencias de escape de los caracteres especiales.

Sintaxis de las funciones de propiedad

Hay tres tipos de funciones de propiedad; cada tipo tiene una sintaxis diferente:

• Funciones de propiedad de cadena (instancia)
• Funciones de propiedad estáticas
• Funciones de propiedad de MSBuild

Funciones de propiedad de cadenas

Todos los valores de las funciones compiladas son solo valores de cadena. Puede usar los métodos de cadena (instancia) para operar en cualquier valor de propiedad. Por ejemplo, puede extraer el nombre del disco (los tres primeros caracteres) de una propiedad del entorno de compilación que representa una ruta de acceso completa mediante este código:

$(ProjectOutputFolder.Substring(0,3))

Funciones de propiedad estáticas

En el script de compilación, puede acceder a las propiedades y métodos estáticos de muchas clases del sistema. Para obtener el valor de una propiedad estática, use la sintaxis siguiente, donde Class es el nombre de la clase del sistema y Property es el nombre de la propiedad .

$([Class]::Property)

Por ejemplo, puede usar el código siguiente para establecer una propiedad de compilación en la fecha y hora actuales.

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

Para llamar a un método estático, use la sintaxis siguiente, donde Class es el nombre de la clase del sistema, Method es el nombre del método y (Parameters) es la lista de parámetros del método:

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

Por ejemplo, para establecer una propiedad de compilación en un nuevo GUID, puede usar este script:

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

En el caso de los métodos sobrecargados, MSBuild intenta encontrar un método con parámetros coincidentes.

En MSBuild 17.14 y versiones posteriores, puede usar la sintaxis out _ de parámetros para especificar un out parámetro. Consulte Parámetros de referencia. El valor del out parámetro se omite. Por ejemplo:

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

La propiedad IsInteger es true si la entrada se analiza correctamente como un entero, pero se omite el valor analizado.

En las funciones de propiedades estáticas, puede usar cualquier método estático público o propiedad definida en .NET Standard 2.0 para estas clases del sistema:

• System.Byte
• System.Char
• System.Convert
• System.DateTime
• System.DateTimeOffset (disponible en MSBuild 17.3 y versiones posteriores)
• 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

Además, puede usar los siguientes métodos estáticos y propiedades:

• 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>

Llamada a métodos de instancia en propiedades estáticas

Si tiene acceso a una propiedad estática que devuelve una instancia de objeto, puede invocar los métodos de instancia de ese objeto. Para invocar un método de instancia, use la sintaxis siguiente, donde Class es el nombre de la clase del sistema, Property es el nombre de la propiedad , Method es el nombre del método y (Parameters) es la lista de parámetros del método:

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

El nombre de la clase debe ser completo en el espacio de nombres.

Por ejemplo, puede usar el código siguiente para establecer una propiedad de compilación en la fecha de hoy.

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

Funciones de propiedad de MSBuild

Puede acceder a varios métodos estáticos de su compilación para proporcionar compatibilidad con operadores aritméticos, lógicos bit a bit y caracteres de escape. Puede acceder a estos métodos mediante la sintaxis siguiente, donde Method es el nombre del método y (Parameters) es la lista de parámetros del método.

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

Por ejemplo, para agregar dos propiedades que tienen valores numéricos, use el código siguiente.

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

Aquí tienes una lista de funciones de propiedades de MSBuild:

Funciones de propiedad anidadas

Puede combinar funciones de propiedad para formar funciones más complejas, como se muestra en el ejemplo siguiente:

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

En este ejemplo se devuelve el valor de .FileAttributes Archive bits (32 o 0) del archivo que da la ruta de acceso tempFile. Observe que los valores de datos enumerados no pueden aparecer por nombre en algunos contextos. En el ejemplo anterior, se debe usar el valor numérico (32) en su lugar. En otros casos, en función de las expectativas del método llamado, se debe usar el valor de los datos de enumeración. En el ejemplo siguiente, el valor de enumeración RegexOptions. ECMAScript debe usarse porque no se puede convertir un valor numérico como espera este método.

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

Los metadatos también pueden aparecer en funciones de propiedades anidadas. Para obtener más información, consulte Procesamiento por lotes.

DoesTaskHostExist de MSBuild

La DoesTaskHostExist función de propiedad en MSBuild devuelve si un host de tareas está instalado actualmente para los valores de tiempo de ejecución y arquitectura especificados.

Esta función de propiedad tiene la sintaxis siguiente:

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

MSBuild EnsureTrailingSlash

La EnsureTrailingSlash función de propiedad de MSBuild agrega una barra diagonal final si aún no existe una.

Esta función de propiedad tiene la sintaxis siguiente:

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

GetDirectoryNameOfFileAbove de MSBuild

La función de propiedad GetDirectoryNameOfFileAbove de MSBuild busca hacia arriba un directorio que contenga el archivo especificado, empezando por el directorio indicado (incluido este). Devuelve la ruta de acceso completa del directorio más cercano que contiene el archivo si se encuentra, de lo contrario, una cadena vacía.

Esta función de propiedad tiene la sintaxis siguiente:

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

En este ejemplo se muestra cómo importar el archivo EnlistmentInfo.props más cercano en o encima de la carpeta actual, solo si se encuentra una coincidencia:

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

Este ejemplo se puede escribir de forma más concisa mediante la GetPathOfFileAbove función en su lugar:

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

MSBuild GetPathOfFileAbove

La función de propiedad GetPathOfFileAbove de MSBuild busca hacia arriba un directorio que contenga el archivo especificado, empezando por el directorio indicado (incluido este). Devuelve la ruta de acceso completa del archivo coincidente más cercano si se encuentra, de lo contrario, una cadena vacía.

Esta función de propiedad tiene la sintaxis siguiente:

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

donde file es el nombre del archivo que se va a buscar y startingDirectory es un directorio opcional en el que iniciar la búsqueda. De forma predeterminada, la búsqueda se inicia en el directorio propio del archivo actual.

En este ejemplo se muestra cómo importar un archivo denominado dir.props en o encima del directorio actual, solo si se encuentra una coincidencia:

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

que es funcionalmente equivalente a

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

Sin embargo, a veces es necesario iniciar la búsqueda en el directorio primario para evitar que coincida con el archivo actual. En este ejemplo se muestra cómo un archivo Directory.Build.props puede importar el archivo Directory.Build.props más cercano en un nivel estrictamente superior del árbol, sin importarse de forma recursiva:

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

que es funcionalmente equivalente a

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

GetRegistryValue de MSBuild

La función de propiedad DE MSBuild GetRegistryValue devuelve el valor de una clave del Registro. Esta función toma dos argumentos, el nombre de clave y el nombre del valor, y devuelve el valor del Registro. Si no especifica un nombre de valor, se devuelve el valor predeterminado.

En los ejemplos siguientes se muestra cómo se usa esta función:

$([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 (Función de MSBuild para obtener valores del registro desde una vista)

La función de propiedad MSBuild GetRegistryValueFromView obtiene los datos del registro del sistema siempre que se proporcionen la clave, el valor y una o varias vistas del registro ordenadas. La clave y el valor se buscan en las vistas del registro secuencialmente hasta que se encuentren.

La sintaxis de esta función de propiedad es:

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

El sistema operativo Windows de 64 bits mantiene una clave del Registro deHKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node que presenta una vista del Registro deHKEY_LOCAL_MACHINE\SOFTWARE para aplicaciones de 32 bits.

De forma predeterminada, una aplicación de 32 bits que se ejecuta en WOW64 accede a la vista del Registro de 32 bits y una aplicación de 64 bits accede a la vista del Registro de 64 bits.

Están disponibles las siguientes vistas del Registro:

A continuación se muestra un ejemplo.

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

El código anterior obtiene los datos SLRuntimeInstallPath de la clave ReferenceAssemblies, buscando primero en la vista de registro de 64 bits y luego en la de 32 bits.

MakeRelative de MSBuild

La función de propiedad MakeRelative de MSBuild devuelve la ruta de acceso relativa de la segunda ruta de acceso, relativa a la primera ruta de acceso. Cada ruta de acceso puede ser un archivo o una carpeta.

Esta función de propiedad tiene la sintaxis siguiente:

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

El código siguiente es un ejemplo de esta sintaxis.

<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

La función de propiedad MSBuild StableStringHash acepta un argumento de cadena y devuelve un código hash que se garantiza que es estable, lo que significa que siempre se devuelve el mismo código para la misma entrada de cadena. El hash devuelto es el mismo, independientemente de si se usa MSBuild o dotnet build, y es estable en la arquitectura de la plataforma, a diferencia del método .NET GetHashCode. No se garantiza que sea estable en diferentes versiones de MSBuild.

Esta función está disponible en MSBuild 16.9.0 o posterior.

En el ejemplo siguiente se muestra cómo se usa esta función.

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

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

Con la versión 17.10 y posteriores de MSBuild, esta función acepta el segundo argumento opcional que solicita que se use el algoritmo hash:

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

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

El segundo argumento no distingue mayúsculas de minúsculas y actualmente admite los siguientes valores:

• Heredado: conserva la misma acción de llamar a la función sin el segundo argumento. Devuelve un entero de 32 bits con signo con propiedades similares a string.GetHashCode.
• Fnv1a32bit: devuelve un entero de 32 bits con signo que representa un hash Fowler–Noll–Vo de la versión "1a" de la cadena especificada.
• Fnv1a64bit: devuelve un entero de 64 bits con signo que representa un hash Fowler–Noll–Vo de la versión "1a" de la cadena especificada.
• Sha256: devuelve una cadena hexadecimal sin prefijo que representa un hash SHA256 de la cadena especificada.

ValueOrDefault de MSBuild

La función de propiedad MSBuild ValueOrDefault devuelve el primer argumento, a menos que sea null o vacío. Si el primer argumento es null o está vacío, la función devuelve el segundo argumento.

En el ejemplo siguiente se muestra cómo se usa esta función.

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

Funciones TargetFramework y TargetPlatform de MSBuild

MSBuild 16.7 y versiones posteriores definen varias funciones para controlar las propiedades TargetFramework y TargetPlatform.

El versionPartCount parámetro de GetTargetFrameworkVersion y GetTargetPlatformVersion tiene un valor predeterminado de 2.

En el ejemplo siguiente se muestra cómo se usan estas funciones.

<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

Funciones de comparación de versiones de MSBuild

MSBuild 16.5 y versiones posteriores definen varias funciones para comparar cadenas que representan versiones.

En estos métodos, las versiones se analizan como System.Version, con las siguientes excepciones:

• El elemento inicial v o V se omite, lo que permite la comparación con $(TargetFrameworkVersion).

• Se omite todo desde el primer "-" o "+" hasta el final de la cadena de versión. Esto permite pasar versiones semánticas (semver), aunque el orden no es el mismo que el de semver. En su lugar, los especificadores de versión preliminar y los metadatos de compilación no tienen ningún peso de ordenación. Esto puede ser útil, por ejemplo, para activar una característica para >= x.y y hacer que se inicie en x.y.z-pre.

• Las partes no especificadas son iguales que las partes de valor cero. (x == x.0 == x.0.0 == x.0.0.0).

• No se permite el espacio en blanco en componentes enteros.

• La versión principal solo es válida (3 es igual a 3.0.0.0)

• + no se permite como signo positivo en los componentes enteros (se trata como metadatos de semver y se ignora)

Funciones de condición de MSBuild

Las funciones Exists y HasTrailingSlash no son funciones de propiedad. Están disponibles para su uso con el Condition atributo . Consulte las condiciones de MSBuild .

Contenido relacionado

• Propiedades de MSBuild

• información general de MSBuild