Поделиться через

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

Функции свойств — это вызовы методов .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>

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

Замечание

Методы и свойства, которые не определены в .NET Standard 2.0, могут быть доступны при использовании MSBuild в среде, поддерживающей их, но не могут быть доступны во всех ситуациях. По соображениям совместимости они лучше всего избегать.

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

Функции свойств System.OperatingSystem

Функции System.OperatingSystem свойств возвращают сведения об операционной системе, в которой выполняется MSBuild. Например, если проект предназначен для Linux и вы создаете его на macOS, функции свойств возвращают сведения о macOS.

В MSBuild, работающем в .NET (dotnet build), все статические методы System.OperatingSystem класса будут вызываться как статические функции свойств.

В MSBuild, работающем на .NET Framework (MSBuild.exe), только следующие методы System.OperatingSystem будут вызываться как статические функции свойств. MSBuild реализует их внутренне, так как System.OperatingSystem не определяет их в .NET Framework. Методы для операционных систем, для которых нет пакета SDK для .NET, например System.OperatingSystem::IsTvOS, не вызываются.

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

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

Сигнатура функции Описание
double Add(double a, double b) Добавьте два двойника.
long Add(long a, long b) Добавьте два длинных целых числа.
double Subtract(double a, double b) Вычитать два двойника.
long Subtract(long a, long b) Вычесть два значения типа long.
double Multiply(double a, double b) Умножьте два раза в два раза.
long Multiply(long a, long b) Умножьте два длинных.
double Divide(double a, double b) Разделить два двойника.
long Divide(long a, long b) Разделить два длинных целых числа.
double Modulo(double a, double b) Модуло два двойных.
long Modulo(long a, long b) Деление по модулю двух длинных целых чисел.
string Escape(string unescaped) Выполните экранирование строки в соответствии с правилами MSBuild.
string Unescape(string escaped) Расэкранируйте строку в соответствии с правилами экранирования MSBuild.
int BitwiseOr(int first, int second) Выполните битовую операцию OR на первой и второй (первая | вторая).
int BitwiseAnd(int first, int second) Выполните побитовую операцию AND для первого и второго.
int BitwiseXor(int first, int second) Выполните битовую побитовую операцию XOR на первом и втором (первый ^ второй).
int BitwiseNot(int first) Выполните битовую операцию NOT (~first).
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, если указано.
string GetDirectoryNameOfFileAbove(string startingDirectory, string fileName) Найдите и верните каталог файла в указанном каталоге или расположении в структуре каталогов выше этого каталога.
string MakeRelative(string basePath, string path) Делает path относительно basePath. basePath должен быть абсолютным каталогом. Если path не удается сделать относительным, он возвращается как есть. Аналогично Uri.MakeRelativeUri.
string ValueOrDefault(string conditionValue, string defaultValue) Возвращает строку в параметре, только если параметр defaultValueconditionValue пуст, в противном случае возвращает значение conditionValue.
string ConvertToBase64(string toEncode) Возвращает строку после преобразования всех байтов в базовые 64 (буквенно-цифровые символы плюс + и /), заканчивающуюся одним или двумя =.
string ConvertFromBase64(string toDecode) Возвращает строку после преобразования из базового 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

Функция свойства 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

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

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

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-разрядному представлению реестра.

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

Вид реестра Определение
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 для .NET MSBuild (dotnet build) эта функция не поддерживается.

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.0 эта функция принимает второй, необязательный аргумент, запрашивающий алгоритм хэширования для использования:

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

Связанный контент