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

  • Статья

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

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

В строковых значениях, возвращаемых из функций свойства, специальные символы преобразованы в escape-символы. Если нужно, чтобы значение обрабатывалось как значение непосредственно в файле проекта, воспользуйтесь функцией $([MSBuild]::Unescape()), чтобы преобразовать специальные символы в обычный формат.

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

Существуют три типа функций свойства, каждая из которых имеет свой синтаксис.

  • Функции свойства строки (экземпляра)
  • Функции статичного свойства
  • Функции свойства MSBuild

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

Все значения свойства построения являются значениями строки. Для управления значением свойства можно использовать методы строки (экземпляра). Например, можно извлечь имя диска (первые три символа) из свойства построения, которое представляет собой полный путь, с помощью следующего кода.

$(ProjectOutputFolder.Substring(0,3))

Функции статичного свойства

В скрипте построения можно получить доступ к статическим свойствам и методам многих системных классов. Чтобы получить значение статического свойства, используйте следующий синтаксис, где Class — имя системного класса, а Property1 — имя свойства.

$([Class]::Property)

Например, чтобы задать свойство построения на текущую дату и время, можно использовать следующий код.

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

Чтобы вызвать статический метод, используйте следующий синтаксис, где Class — имя системного класса, Method — имя метода, а (Parameters) — список параметров метода:

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

Например, чтобы задать свойство построения на новый GUID, можно использовать следующий скрипт.

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

В статических функциях свойств можно использовать любой открытый статический метод или свойство следующих системных классов:

Кроме этого, можно использовать следующие статические методы и свойства.

Вызов методов экземпляра для статических свойств

При доступе к статическому свойству, которое возвращает экземпляр объектов, можно вызывать методы экземпляра этого объекта. Чтобы вызвать метод экземпляра, используйте следующий синтаксис, где Class — имя системного класса, Property — имя свойства, Method — имя метода и (Parameters) — список параметров метода:

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

Имя класса должно содержать полное пространство имен.

Например, чтобы задать свойство построения на текущую дату, можно использовать следующий код.

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

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

Для обеспечения арифметической побитовой логической поддержки escape-символов можно использовать несколько статических методов из вашего построения. Доступ к этим методам осуществляется с помощью следующего синтаксиса, где Method — это имя метода, а (Parameters) — список параметров для метода.

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

Например, чтобы добавить два свойства с числовыми значениями, используйте следующий код.

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

Приведем список функций свойства MSBuild.

Сигнатура функции Описание
double Add(double a, double b) Сложение двух значений double.
long Add(long a, long b) Сложение двух значений long.
double Subtract(double a, double b) Вычитание двух значений double.
long Subtract(long a, long b) Вычитание двух значений long.
double Multiply(double a, double b) Умножение двух значений double.
long Multiply(long a, long b) Умножение двух значений long.
double Divide(double a, double b) Деление двух значений double.
long Divide(long a, long b) Деление двух значений long.
double Modulo(double a, double b) Остаток от деления двух значений double.
long Modulo(long a, long b) Остаток от деления двух значений long.
string Escape(string unescaped) Escape-последовательность строки в соответствии с правилами экранирования MSBuild.
string Unescape(string escaped) Unescape-последовательность строки в соответствии с правилами экранирования MSBuild.
int BitwiseOr(int first, int second) Примените побитовый параметр OR к первому и второму значению (first | second).
int BitwiseAnd(int first, int second) Примените побитовый параметр AND к первому и второму значению (first & second).
int BitwiseXor(int first, int second) Примените побитовый параметр XOR к первому и второму значению (первое ^ второе).
int BitwiseNot(int first) Примените побитовый параметр NOT (~первое значение).
bool IsOsPlatform(string platformString) Указание того, является ли текущая платформа ОС platformString. platformString должен быть элементом OSPlatform.
bool IsOSUnixLike() Значение true, если текущая операционная система — это система Unix.
string NormalizePath(params string[] path) Возвращает канонический полный путь для предоставленного пути и проверяет правильность знаков разделения для каталогов, используемых в текущей операционной системе.
string NormalizeDirectory(params string[] path) Возвращает канонический полный путь для предоставленного каталога и проверяет правильность знаков разделения для каталогов, используемых в текущей операционной системе, а также наличие косой черты в конце.
string EnsureTrailingSlash(string path) Если в конце заданного пути нет косой черты, она добавляется. Если путь является пустой строкой, он не изменяется.
string GetPathOfFileAbove(string file, string startingDirectory) Выполняет поиск и возвращает полный путь к файлу в структуре каталогов в расположении текущего файла сборки или на основе startingDirectory, если он указан.
GetDirectoryNameOfFileAbove(string startingDirectory, string fileName) Поиск и возврат каталога файла в указанном каталоге либо расположении в структуре каталогов над ним.
string MakeRelative(string basePath, string path) Делает path относительным для basePath. basePath должен быть абсолютным каталогом. Если path невозможно сделать относительным, он возвращается дословно. Аналогично Uri.MakeRelativeUri.
string ValueOrDefault(string conditionValue, string defaultValue) Возвращает строку в параметре defaultValue , только если параметр conditionValue пуст, в противном случае возвращается значение conditionValue.
string ConvertToBase64(string toEncode) Возвращает строку после преобразования всех байтов в базовые 64 (буквенно-цифровые символы плюс + и /), оканчиваясь одним или двумя =.
string ConvertFromBase64(string toDecode) Возвращает строку после преобразования из base 64 (буквенно-цифровые символы плюс + и /), заканчивая одним или двумя =.

Вложенные функции свойства

Вы можете объединить функции свойств для формирования более сложных функций, как показано в следующем примере:

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

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

Эта функция свойства использует следующий синтаксис.

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

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

Эта функция свойства использует следующий синтаксис.

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

Функция свойства GetRegistryValue в MSBuild возвращает значение раздела реестра. Она принимает два аргумента — имя раздела и имя значения — и возвращает значение в реестр. Если не указано имя значения, возвращается значение по умолчанию.

В следующих примерах показано, как используется эта функция.

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

Предупреждение

В версии пакета SDK MSBuild (dotnet build) для .NET, эта функция не поддерживаются.

MSBuild GetRegistryValueFromView

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

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

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

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

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

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

Представление реестра Определение
RegistryView.Registry32 Представление реестра для 32-разрядного приложения.
RegistryView.Registry64 Представление реестра для 64-разрядного приложения.
RegistryView.Default Представление реестра, совпадающее с процессом, на котором работает приложение.

Пример.

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

В этом примере данные SLRuntimeInstallPath получаются из раздела ReferenceAssemblies, но сначала поиск выполняется в 64-разрядном представлении реестра, а затем — в 32-разрядном.

Предупреждение

В версии пакета SDK MSBuild (dotnet build) для .NET, эта функция не поддерживаются.

MSBuild MakeRelative

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

Эта функция свойства использует следующий синтаксис.

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

Функция свойства ValueOrDefault в MSBuild возвращает первый аргумент, если он не нулевой или пустой. Если первый аргумент нулевой, функция возвращает второй аргумент.

В следующем примере показано, как используется эта функция.

<Project ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">

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

Сигнатура функции Описание
GetTargetFrameworkIdentifier(string targetFramework) Анализирует TargetFrameworkIdentifier из TargetFramework.
GetTargetFrameworkVersion(string targetFramework, int versionPartCount) Анализирует TargetFrameworkVersion из TargetFramework.
GetTargetPlatformIdentifier(string targetFramework) Анализирует TargetPlatformIdentifier из TargetFramework.
GetTargetPlatformVersion(string targetFramework, int versionPartCount) Анализирует TargetPlatformVersion из TargetFramework.
IsTargetFrameworkCompatible(string targetFrameworkTarget, string targetFrameworkCandidate) Возвращает значение True, если целевая платформа-кандидат (второй аргумент) совместима с целевой платформой, указанной первым аргументом, и значение false в противном случае.

По умолчанию для параметра versionPartCountGetTargetFrameworkVersion и GetTargetPlatformVersion установлено значение 2.

В следующем примере показано, как используются эти функции.

<Project ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">

    <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>
    </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)" />
    </Target>
</Project>

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

Функции сравнения версий MSBuild

MSBuild 16.5 и выше определяет несколько функций для сравнения строк, представляющих версии.

Примечание

Операторы сравнения в условиях могут сравнивать строки, которые могут быть проанализированы как объекты System.Version, но сравнение может привести к непредвиденным результатам. Предпочитать функции свойств.

Сигнатура функции Описание
VersionEquals(string a, string b) Возвращает true, если версии a и b эквивалентны, согласно указанным ниже правилам.
VersionGreaterThan(string a, string b) Возвращает true, если версия a выше версии b, согласно указанным ниже правилам.
VersionGreaterThanOrEquals(string a, string b) Возвращает true, если версия a выше или равна версии b, согласно указанным ниже правилам.
VersionLessThan(string a, string b) Возвращает true, если версия a ниже версии b, согласно указанным ниже правилам.
VersionLessThanOrEquals(string a, string b) Возвращает true, если версия a ниже или равна версии b, согласно указанным ниже правилам.
VersionNotEquals(string a, string b) Возвращает false, если версии a и b эквивалентны, согласно указанным ниже правилам.

В этих методах синтаксический анализ версий выполняется так же 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 и игнорируется)

Совет

Сравнения свойств TargetFramework обычно должны использовать IsTargetFrameworkCompatible вместо извлечения и сравнения версий. Это позволяет сравнивать TargetFramework, которые имеют разные TargetFrameworkIdentifier, помимо версии.

Функции условий MSBuild

Функции Exists и HasTrailingSlash не являются функциями элементов. Они доступны для использования с атрибутом Condition. См. Условия MSBuild.

См. также