Функции свойств

Функции свойств — это вызовы методов .NET, которые отображаются в определениях свойств MSBuild. Обычно они используются для создания определений свойств, требующих более сложной логики.

В отличие от задач, функции свойств можно использовать вне целевых объектов. Функции свойств выполняются каждый раз, когда свойства или элементы расширяются. Таким образом, для свойств и элементов вне каких-либо целевых объектов функции свойств оцениваются перед любым целевым запуском. Для групп свойств и групп элементов внутри целевых объектов функции свойств оцениваются при выполнении целевого объекта.

Без использования задач 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::P rocessorCount
• 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::GetDirectory
• 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 имя системного класса, Property является именем свойства, Method является именем метода и (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 бит (32 или 0) файла, указанного по пути tempFile. Обратите внимание, что перечисленные значения данных не могут отображаться по имени в некоторых контекстах. В предыдущем примере вместо этого необходимо использовать числовое значение (32). В других случаях в зависимости от ожиданий вызываемого метода необходимо использовать значение данных перечисления. В следующем примере значение перечисления RegexOptions. ECMAScript необходимо использовать, так как числовое значение не может быть преобразовано в соответствии с ожиданиями этого метода.

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

Метаданные также могут отображаться в вложенных функциях свойств. Дополнительные сведения см. в разделе "Пакетная обработка".

MSBuild DoesTaskHostExist

Функция свойства DoesTaskHostExist в MSBuild возвращает, установлен ли в настоящее время узел задач для указанных значений среды выполнения и архитектуры.

Эта функция свойства имеет следующий синтаксис:

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

MSBuild EnsureTrailingSlash

Функция EnsureTrailingSlash свойства в MSBuild добавляет слэш в конце, если он отсутствует.

Эта функция свойства имеет следующий синтаксис:

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

Функция свойства MSBuild GetRegistryValueFromView получает данные системного реестра при наличии заданного ключа реестра, значения и одного или нескольких упорядоченных представлений реестра. Ключ и значение ищутся последовательно в каждом представлении реестра, пока не будут найдены.

Синтаксис этой функции свойства:

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

Операционная система Windows 64-разрядной версии поддерживает ключ реестра HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node , который предоставляет представление реестра HKEY_LOCAL_MACHINE\SOFTWARE для 32-разрядных приложений.

По умолчанию 32-разрядное приложение, работающее в WOW64, обращается к 32-разрядному представлению реестра, а 64-разрядное приложение обращается к 64-разрядному представлению реестра.

Доступны следующие представления реестра:

Ниже приведен пример.

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

Предыдущий код получает данные SLRuntimeInstallPath ключа ReferenceAssemblies, сначала ищет в 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 — возвращает подписанное 32-разрядное целое число, представляющее хэш Fowler-Noll-Vo версии 1a для заданной строки.
• Fnv1a64bit — возвращает подписанное 64-разрядное целое число, представляющее хэш Fowler-Noll-Vo версии 1a для заданной строки.
• 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.

Параметр versionPartCountGetTargetFrameworkVersion и 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