属性函数

属性函数是对 MSBuild 属性定义中显示的 .NET 方法的调用。 通常使用它们来构造需要更复杂的逻辑的属性定义。

与任务不同，属性函数可以在目标外部使用。 每当展开属性或项时，都会计算属性函数。 因此，对于任何目标之外的属性和项，将在任何目标运行之前评估属性函数。 对于目标中的属性组和项组，在执行目标时会评估属性函数。

如果不使用 MSBuild 任务，可以读取系统时间、比较字符串、匹配正则表达式，并在生成脚本中执行其他作。 MSBuild 尝试将字符串转换为数字和数字转换为字符串，并根据需要进行其他转换。

从属性函数返回的字符串值已转义特殊字符。 如果要将这些值视为如同直接置于项目文件中，请使用 $([MSBuild]::Unescape()) 取消转义特殊字符。

属性函数语法

有三种类型的属性函数：每种类型都有不同的语法：

• String （instance） 属性函数
• 静态属性函数
• MSBuild 属性函数

字符串属性函数

所有生成属性值只是字符串值。 可以使用字符串（实例）方法对任何属性值进行操作。 例如，可以使用以下代码从表示完整路径的生成属性中提取驱动器名称（前三个字符）：

$(ProjectOutputFolder.Substring(0,3))

静态属性函数

在生成脚本中，可以访问许多系统类的静态属性和方法。 若要获取静态属性的值，请使用以下语法，其中系统 Class 类的名称是 Property 属性的名称。

$([Class]::Property)

例如，可以使用以下代码将生成属性设置为当前日期和时间。

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

若要调用静态方法，请使用以下语法，其中 Class 系统类 Method 的名称是方法的名称，并且 (Parameters) 是方法的参数列表：

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

例如，若要将生成属性设置为新的 GUID，可以使用以下脚本：

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

对于重载的方法，MSBuild 会尝试查找具有匹配参数的方法。

在 MSBuild 17.14 及更高版本中，可以使用参数语法 out _ 指定 out 参数。 请参阅 参考参数。 忽略 out 参数值。 例如：

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

该属性 IsInteger 是 true ，如果输入成功解析为整数，但忽略已分析的值。

在静态属性函数中，可以将 .NET Standard 2.0 中定义的任何公共静态方法或属性用于以下系统类：

• System.Byte
• System.Char
• System.Convert
• System.DateTime
• System.DateTimeOffset （在 MSBuild 17.3 及更高版本中可用）
• 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

此外，可以使用以下静态方法和属性：

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

对静态属性调用实例方法

如果访问返回对象实例的静态属性，则可以调用该对象的实例方法。 若要调用实例方法，请使用以下语法，其中 Class 系统类的名称是属性的名称， PropertyMethod 是方法的名称，是 (Parameters) 方法的参数列表：

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

类名必须使用命名空间进行完整限定。

例如，可以使用以下代码将生成属性设置为当前日期。

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

MSBuild 属性函数

在您的项目构建中，有若干静态方法可访问，以便于提供算术、按位逻辑和转义字符的支持。 使用以下语法访问这些方法，其中方法 Method 的名称是 (Parameters) 该方法的参数列表。

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

例如，若要将具有数值的两个属性相加，请使用以下代码。

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

下面是 MSBuild 属性函数的列表：

嵌套属性函数

可以组合属性函数以形成更复杂的函数，如以下示例所示：

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

此示例返回值 FileAttributes。 路径 Archive 提供的文件的 tempFile 位（32 或 0）。 请注意，枚举的数据值在某些上下文中不能按名称显示。 在前面的示例中，必须改用数值（32）。 在其他情况下，必须使用枚举数据值，这具体取决于所调用方法的要求。 在下面的示例中，必须使用枚举值 RegexOptions.，必须使用 ECMAScript，因为无法按照该方法所期望的方式转换数值。

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

元数据也可能出现在嵌套属性函数中。 有关详细信息，请参阅批处理。

MSBuild DoesTaskHostExist

MSBuild 中的 DoesTaskHostExist 属性函数将返回当前是否针对特定运行时和体系结构值安装了任务宿主。

此属性函数具有以下语法：

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

MSBuild EnsureTrailingSlash

如果尚不存在尾部反斜杠，MSBuild 中的 EnsureTrailingSlash 属性函数将添加一条。

此属性函数具有以下语法：

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

MSBuild GetDirectoryNameOfFileAbove

MSBuild GetDirectoryNameOfFileAbove 属性函数向上搜索包含指定文件的目录，从指定目录开始（包括指定目录）。 如果找到该文件，则返回最接近的目录的完整路径，否则返回一个空字符串。

此属性函数具有以下语法：

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

此示例演示了如何在当前文件夹中或更高一级中导入最近的 EnlistmentInfo.props 文件（仅当找到匹配项时）：

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

使用 GetPathOfFileAbove 函数可以使此示例编写得更简洁。

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

MSBuild GetPathOfFileAbove

MSBuild GetPathOfFileAbove 属性函数向上搜索包含指定文件的目录，从指定目录开始（包括指定目录）。 如果找到最接近的匹配文件，它将返回完整路径，否则返回空字符串。

此属性函数具有以下语法：

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

其中 file 要搜索的文件的名称，是 startingDirectory 启动搜索的可选目录。 默认情况下，搜索从当前文件自己的目录中开始。

此示例演示如何仅当找到匹配项时，才能在当前目录中或上方导入名为 dir.props 的文件：

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

这在功能上等效于

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

但是，有时需要在父目录中启动搜索，以避免匹配当前文件。 此示例演示 Directory.Build.props 文件如何在树的更高级别中导入最近的 Directory.Build.props 文件，而无需递归导入自身：

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

这在功能上等效于

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

MSBuild GetRegistryValue（获取注册表值）

MSBuild GetRegistryValue 属性函数返回注册表项的值。 此函数采用两个参数：键名称和值名称，并从注册表返回值。 如果未指定值名称，则返回默认值。

以下示例演示如何使用此函数：

$([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 从视图中获取注册表值

MSBuild GetRegistryValueFromView 属性函数在给定注册表项、值和一个或多个排序的注册表视图的情况下获取系统注册表数据。 按顺序在每个注册表视图中搜索键和值，直到找到为止。

此属性函数的语法为：

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

Windows 64 位操作系统维护HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node 注册表项，该注册表项为 32 位应用程序提供HKEY_LOCAL_MACHINE\SOFTWARE 注册表视图。

默认情况下，WOW64 上运行的 32 位应用程序访问 32 位注册表视图，64 位应用程序访问 64 位注册表视图。

以下注册表视图可用：

下面是一个示例。

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

前面的代码获取 ReferenceAssemblies 键的 SLRuntimeInstallPath 数据，先在 64 位注册表视图中查找，然后在 32 位注册表视图中查找。

MSBuild MakeRelative

MSBuild MakeRelative 属性函数返回相对于第一个路径的第二个路径的相对路径。 每个路径可以是文件或文件夹。

此属性函数具有以下语法：

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

以下代码是此语法的示例。

<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

MSBuild StableStringHash 属性函数接受字符串参数，并返回一个保证稳定哈希代码，这意味着始终为同一字符串输入返回相同的代码。 无论是使用 MSBuild 还是 dotnet build，返回的哈希值都是相同的，并且在跨平台架构中保持稳定，这一点不同于 .NET 方法 GetHashCode。 不能保证在不同的 MSBuild 版本中保持稳定。

此函数在 MSBuild 16.9.0 或更高版本中可用。

以下示例演示了如何使用此函数。

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

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

对于 MSBuild 版本 17.10 及更高版本，此函数接受第二个可选参数，请求使用哈希算法：

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

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

第二个参数不区分大小写，当前支持以下值：

• 旧版 - 保留与在没有第二个参数的情况下调用函数相同的行为。 返回带符号的 32 位整数，其属性与 string.GetHashCode 相似。
• Fnv1a32bit - 返回表示给定字符串的 Fowler–Noll–Vo 版本“1a”哈希的有符号32位整数。
• Fnv1a64bit - 返回带符号的 64 位整数，此整数表示给定字符串的版本“1a”的 Fowler–Noll–Vo 哈希。
• Sha256 - 返回一个表示给定字符串的 SHA256 哈希的无前缀十六进制字符串。

MSBuild ValueOrDefault

MSBuild ValueOrDefault 属性函数返回第一个参数，除非它为 null 或为空。 如果第一个参数为 null 或为空，则该函数返回第二个参数。

以下示例演示了如何使用此函数。

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

MSBuild TargetFramework 和 TargetPlatform 函数

MSBuild 16.7 及更高版本定义了多个用于处理 TargetFramework 和 TargetPlatform 属性的函数。

versionPartCount与GetTargetFrameworkVersion的GetTargetPlatformVersion参数默认值为 2。

以下示例演示如何使用这些函数。

<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

MSBuild 版本比较函数

MSBuild 16.5 及更高版本定义了多个函数，用于比较表示版本的字符串。

在这些方法中，版本分析方式如下 System.Version，但有以下例外情况：

• 忽略前导 v 或 V，这允许对 $(TargetFrameworkVersion) 进行比较。

• 忽略从第一个“-”或“+”到版本字符串末尾的所有内容。 虽然顺序与 SemVer 不同，但允许传递语义版本 (SemVer)。 相反，预发行版说明符和生成元数据没有任何排序权重。 例如，这在为>= x.y启用功能并使其在x.y.z-pre生效时可能非常有用。

• 未指定的部分与零值部分相同。 (x == x.0 == x.0.0 == x.0.0.0)。

• 整数组件中不允许空格。

• 主版本仅有效（3 等于 3.0.0.0）

• + 不允许作为整数部分中的正号（它被视为 semver 元数据并被忽略）

MSBuild 条件函数

函数 Exists 和 HasTrailingSlash 不是属性函数。 它们可用于属性 Condition 。 请参阅 MSBuild 条件。

相关内容

• MSBuild 属性

• MSBuild 概述