プロパティ関数

プロパティ関数は、MSBuild プロパティ定義に表示される .NET メソッドの呼び出しです。 通常、これらを使用して、より複雑なロジックを必要とするプロパティ定義を構築します。

タスクとは異なり、プロパティ関数はターゲットの外部で使用できます。 プロパティ関数は、プロパティまたは項目が展開されるたびに評価されます。 そのため、ターゲットの外部にあるプロパティと項目の場合、プロパティ関数はターゲットを実行する前に評価されます。 ターゲット内のプロパティ グループと項目グループの場合、ターゲットの実行時にプロパティ関数が評価されます。

MSBuild タスクを使用しないと、システム時刻の読み取り、文字列の比較、正規表現の照合、ビルド スクリプトでのその他のアクションの実行を行うことができます。 MSBuild は、文字列を数値に変換し、数値を文字列に変換し、必要に応じて他の変換を行います。

プロパティ関数から返される文字列値は、特殊文字がエスケープされます。 値をプロジェクト ファイルに直接配置されたかのように扱う場合は、 $([MSBuild]::Unescape()) を使用して特殊文字をエスケープします。

プロパティ関数の構文

プロパティ関数には 3 種類あります。各種類の構文は異なります。

• 文字列 (インスタンス) プロパティ関数
• 静的プロパティ関数
• MSBuild プロパティ関数

文字列プロパティ関数

すべてのビルド プロパティ値は、単なる文字列値です。 文字列 (インスタンス) メソッドを使用して、任意のプロパティ値を操作できます。 たとえば、次のコードを使用して、完全なパスを表すビルド プロパティからドライブ名 (最初の 3 文字) を抽出できます。

$(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 はシステム クラスの名前、 Property はプロパティの名前、 Method はメソッドの名前、 (Parameters) はメソッドのパラメーター リストです。

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

クラスの名前は、名前空間で完全修飾されている必要があります。

たとえば、次のコードを使用して、ビルド プロパティを現在の日付に設定できます。

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

MSBuild プロパティ関数

ビルド内のいくつかの静的メソッドにアクセスして、算術、ビットごとの論理、エスケープ文字のサポートを提供できます。 これらのメソッドには、次の構文を使用してアクセスします。ここで、 Method はメソッドの名前、 (Parameters) はメソッドのパラメーター リストです。

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

たとえば、数値を持つ 2 つのプロパティをまとめて追加するには、次のコードを使用します。

$([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 末尾スラッシュを確実にする

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 プロパティ関数は、レジストリ キーの値を返します。 この関数は、キー名と値名の 2 つの引数を受け取り、レジストリから値を返します。 値名を指定しない場合は、既定値が返されます。

次の例は、この関数の使用方法を示しています。

$([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 プロパティ関数は、レジストリ キー、値、および 1 つ以上の順序付けられたレジストリ ビューを指定して、システム レジストリ データを取得します。 キーと値は、見つかるまで各レジストリ ビューで順番に検索されます。

このプロパティ関数の構文は次のとおりです。

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

Windows 64 ビット オペレーティング システムは、32 ビット アプリケーション のHKEY_LOCAL_MACHINE\SOFTWARE レジストリ ビューを表示する HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node レジストリ キーを保持します。

既定では、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 プロパティ関数は、最初のパスに対する 2 番目のパスの相対パスを返します。 各パスには、ファイルまたはフォルダーを指定できます。

このプロパティ関数には、次の構文があります。

$([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 以降では、この関数は、使用するハッシュ アルゴリズムを要求する 2 番目の省略可能な引数を受け取ります。

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

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

2 番目の引数では大文字と小文字が区別されず、現在、次の値がサポートされています。

• レガシ - 2 番目の引数を指定せずに関数を呼び出す場合と同じ動作を保持します。 string.GetHashCodeと同様のプロパティを持つ符号付き 32 ビット整数を返します。
• Fnv1a32bit - 指定された文字列の バージョン '1a' ハッシュの Fowler-Noll-Vo ハッシュ を表す符号付き 32 ビット整数を返します。
• Fnv1a64bit - 指定された文字列の バージョン '1a' ハッシュの Fowler-Noll-Vo ハッシュ を表す符号付き 64 ビット整数を返します。
• Sha256 - 指定された文字列の SHA256 ハッシュを表す未修正の 16 進文字列を返します。

MSBuild の ValueOrDefault

MSBuild ValueOrDefault プロパティ関数は、null または空でない限り、最初の引数を返します。 最初の引数が null または空の場合、関数は 2 番目の引数を返します。

次の例は、この関数の使用方法を示しています。

<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を開始する場合などに便利です。

• 指定されていない部分は、0 個の値の部分と同じです。 (x == x.0 == x.0.0 == x.0.0.0)。

• 空白は整数コンポーネントでは使用できません。

• メジャー バージョンのみが有効です (3 は 3.0.0.0 と等しい)

• + は、整数コンポーネントの正符号として許可されていません (semver メタデータとして扱われ、無視されます)

MSBuild 条件関数

Exists関数とHasTrailingSlash関数はプロパティ関数ではありません。 Condition属性で使用できます。 MSBuild の条件を参照してください。

関連コンテンツ

• MSBuild プロパティ

• MSBuild の概要