Use property functions to call .NET methods – MSBuild

Property functions are calls to .NET methods that appear in MSBuild property definitions. You typically use them to construct property definitions that require more complex logic.

Unlike tasks, property functions can be used outside of targets. Property functions are evaluated whenever the properties or items get expanded. So, for properties and items outside of any targets, property functions are evaluated before any target runs. For property groups and item groups inside targets, property functions are evaluated when the target is executed.

Without using MSBuild tasks, you can read the system time, compare strings, match regular expressions, and perform other actions in your build script. MSBuild tries to convert string to number and number to string, and make other conversions as required.

String values returned from property functions have special characters escaped. If you want the value to be treated as though it was put directly in the project file, use $([MSBuild]::Unescape()) to unescape the special characters.

Property function syntax

There are three kinds of property functions; each kind has a different syntax:

• String (instance) property functions
• Static property functions
• MSBuild property functions

String property functions

All build property values are just string values. You can use string (instance) methods to operate on any property value. For example, you can extract the drive name (the first three characters) from a build property that represents a full path by using this code:

$(ProjectOutputFolder.Substring(0,3))

Static property functions

In your build script, you can access the static properties and methods of many system classes. To get the value of a static property, use the following syntax, where Class is the name of the system class and Property is the name of the property.

$([Class]::Property)

For example, you can use the following code to set a build property to the current date and time.

$([System.DateTime]::Now)

To call a static method, use the following syntax, where Class is the name of the system class, Method is the name of the method, and (Parameters) is the parameter list for the method:

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

For example, to set a build property to a new GUID, you can use this script:

$([System.Guid]::NewGuid())

For overloaded methods, MSBuild tries to find a method with matching parameters.

In MSBuild 17.14 and later, you can use the parameter syntax out _ to specify an out parameter. See Reference parameters. The out parameter value is ignored. For example:

$([System.Int32]::TryParse("123", out _))

The property IsInteger is true if the input is successfully parsed as an integer, but the parsed value is ignored.

In static property functions, you can use any public static method or property defined in .NET Standard 2.0 for these system classes:

In addition, you can use the following static methods and properties:

$([System.OperatingSystem]::IsWindows())

Calling instance methods on static properties

If you access a static property that returns an object instance, you can invoke the instance methods of that object. To invoke an instance method, use the following syntax, where Class is the name of the system class, Property is the name of the property, Method is the name of the method, and (Parameters) is the parameter list for the method:

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

The name of the class must be fully qualified with the namespace.

For example, you can use the following code to set a build property to the current date today.

$([System.DateTime]::Now.ToString('yyyy.MM.dd'))

MSBuild property functions

Several static methods in your build can be accessed to provide arithmetic, bitwise logical, and escape character support. You access these methods by using the following syntax, where Method is the name of the method and (Parameters) is the parameter list for the method.

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

For example, to add together two properties that have numeric values, use the following code.

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

Here’s a list of MSBuild property functions:

Nested property functions

You can combine property functions to form more complex functions, as the following example shows:

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

This example returns the value of the FileAttributes.Archive bit (32 or 0) of the file given by the path tempFile. Notice that enumerated data values cannot appear by name in some contexts. In the previous example, the numeric value (32) must be used instead. In other cases, depending on the expectations of the method called, the enum data value must be used. In the following example, the enum value RegexOptions.ECMAScript must be used because a numeric value cannot be converted as this method expects.

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

Metadata may also appear in nested property functions. For more information, see Batching.

MSBuild DoesTaskHostExist

The DoesTaskHostExist property function in MSBuild returns whether a task host is currently installed for the specified runtime and architecture values.

This property function has the following syntax:

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

MSBuild EnsureTrailingSlash

The EnsureTrailingSlash property function in MSBuild adds a trailing slash if one doesn’t already exist.

This property function has the following syntax:

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

MSBuild GetDirectoryNameOfFileAbove

The MSBuild GetDirectoryNameOfFileAbove property function searches upward for a directory containing the specified file, beginning in (and including) the specified directory. It returns the full path of the nearest directory containing the file if it is found, otherwise an empty string.

This property function has the following syntax:

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

This example shows how to import the nearest EnlistmentInfo.props file in or above the current folder, only if a match is found:

This example can be written more concisely by using the GetPathOfFileAbove function instead:

MSBuild GetPathOfFileAbove

The MSBuild GetPathOfFileAbove property function searches upward for a directory containing the specified file, beginning in (and including) the specified directory. It returns the full path of the nearest matching file if it is found, otherwise an empty string.

This property function has the following syntax:

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

where file is the name of the file to search for and startingDirectory is an optional directory to start the search in. By default, the search starts in the current file’s own directory.

This example shows how to import a file named dir.props in or above the current directory, only if a match is found:

which is functionally equivalent to

However, sometimes you need to start the search in the parent directory, to avoid matching the current file. This example shows how a Directory.Build.props file can import the nearest Directory.Build.props file in a strictly higher level of the tree, without recursively importing itself:

which is functionally equivalent to

MSBuild GetRegistryValue

The MSBuild GetRegistryValue property function returns the value of a registry key. This function takes two arguments, the key name and the value name, and returns the value from the registry. If you don’t specify a value name, the default value is returned.

The following examples show how this function is used:

$([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

The MSBuild GetRegistryValueFromView property function gets system registry data given the registry key, value, and one or more ordered registry views. The key and value are searched in each registry view in order until they are found.

The syntax for this property function is:

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

The Windows 64-bit operating system maintains a HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node registry key that presents a HKEY_LOCAL_MACHINE\SOFTWARE registry view for 32-bit applications.

By default, a 32-bit application running on WOW64 accesses the 32-bit registry view and a 64-bit application accesses the 64-bit registry view.

The following registry views are available:

The following is an example.

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

The preceding code gets the SLRuntimeInstallPath data of the ReferenceAssemblies key, looking first in the 64-bit registry view and then in the 32-bit registry view.

MSBuild MakeRelative

The MSBuild MakeRelative property function returns the relative path of the second path relative to first path. Each path can be a file or folder.

This property function has the following syntax:

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

The following code is an example of this syntax.

    c:\users\
    c:\users\username\



    
    

MSBuild StableStringHash

The MSBuild StableStringHash property function accepts a string argument, and returns a hash code that is guaranteed to be stable, meaning that the same code is always returned for the same string input. The returned hash is the same regardless of whether MSBuild or dotnet build is used, and is stable across platform architecture, unlike the .NET method GetHashCode. It is not guaranteed to be stable across different MSBuild versions.

This function is available in MSBuild 16.9.0 or later.

The following example shows how this function is used.

   
      $([MSBuild]::StableStringHash("test1"))
   

   
      
   

With MSBuild version 17.10 and later, this function accepts second, optional, argument requesting the hashing algorithm to be used:

   
      $([MSBuild]::StableStringHash("test1", "Sha256"))
   

   
      
   

The second argument is case insensitive and currently supports following values:

• Legacy – keeps the same behavior as calling the function without the second argument. Returns signed 32bit integer with similar properties as string.GetHashCode.
• Fnv1a32bit – Returns signed 32bit integer representing a Fowler–Noll–Vo hash of version ‘1a’ hash of the given string.
• Fnv1a64bit – Returns signed 64bit integer representing a Fowler–Noll–Vo hash of version ‘1a’ hash of the given string.
• Sha256 – Returns unprefixed hex string representing a SHA256 hash of the given string.

MSBuild ValueOrDefault

The MSBuild ValueOrDefault property function returns the first argument, unless it’s null or empty. If the first argument is null or empty, the function returns the second argument.

The following example shows how this function is used.

    
        $([MSBuild]::ValueOrDefault('$(UndefinedValue)', 'a'))
        $([MSBuild]::ValueOrDefault('b', '$(Value1)'))
    

    
        
        
    

MSBuild TargetFramework and TargetPlatform functions

MSBuild 16.7 and higher define several functions for handling TargetFramework and TargetPlatform properties.

The versionPartCount parameter of GetTargetFrameworkVersion and GetTargetPlatformVersion has a default value of 2.

The following example shows how these functions are used.

    
        $([MSBuild]::GetTargetFrameworkIdentifier('net5.0-windows7.0'))
        $([MSBuild]::GetTargetFrameworkVersion('net5.0-windows7.0'))
        $([MSBuild]::GetTargetPlatformIdentifier('net5.0-windows7.0'))
        $([MSBuild]::GetTargetPlatformVersion('net5.0-windows7.0'))
        $([MSBuild]::IsTargetFrameworkCompatible('net5.0-windows', 'net5.0'))
        $([MSBuild]::IsTargetFrameworkCompatible('net5.0', 'net6.0'))
        $([MSBuild]::IsTargetFrameworkCompatible('net5.0', 'net8.0'))
        $([MSBuild]::IsTargetFrameworkCompatible('net8.0', 'net6.0'))
    

    
        
        
        
        
        
        
        
        
    

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

MSBuild version-comparison functions

MSBuild 16.5 and higher define several functions for comparing strings that represent versions.

In these methods, versions are parsed like System.Version, with the following exceptions:

• Leading v or V is ignored, which allows comparison to $(TargetFrameworkVersion).

• Everything from the first ‘-‘ or ‘+’ to the end of the version string is ignored. This allows passing in semantic versions (semver), though the order is not the same as semver. Instead, prerelease specifiers and build metadata do not have any sorting weight. This can be useful, for example, to turn on a feature for >= x.y and have it kick in on x.y.z-pre.

• Unspecified parts are same as zero value parts. (x == x.0 == x.0.0 == x.0.0.0).

• Whitespace is not allowed in integer components.

• Major version only is valid (3 is equal to 3.0.0.0)

• + is not allowed as positive sign in integer components (it is treated as semver metadata and ignored)

MSBuild condition functions

The functions Exists and HasTrailingSlash are not property functions. They’re available for use with the Condition attribute. See MSBuild conditions.

Related content