Funkce vlastností

Funkce vlastností jsou volání metod .NET, které se zobrazují v definicích vlastností MSBuild. Na rozdíl od úkolů je možné použít funkce vlastností mimo cíle. Funkce vlastností se vyhodnocují při každém rozbalení vlastností nebo položek. U vlastností a položek mimo jakékoli cíle se proto funkce vlastností vyhodnocují před jakýmkoli cílovým spuštěním. U skupin vlastností a skupin položek uvnitř cílů se funkce vlastností vyhodnocují při vyhodnocování cíle.

Bez použití úloh NÁSTROJE MSBuild můžete číst systémový čas, porovnávat řetězce, odpovídat regulárním výrazům a provádět další akce ve skriptu sestavení. NÁSTROJ MSBuild se pokusí převést řetězec na číslo a číslo na řetězec a podle potřeby provede další převody.

Řetězcové hodnoty vrácené z funkcí vlastností mají speciální řídicí znaky . Pokud chcete, aby se hodnota zpracovávala, jako by byla vložena přímo do souboru projektu, použijte $([MSBuild]::Unescape()) k zrušení přehledu speciálních znaků.

Syntaxe funkce vlastnosti

Jedná se o tři druhy vlastností; každá funkce má jinou syntaxi:

• Funkce vlastností String (instance)
• Statické funkce vlastností
• Funkce vlastností NÁSTROJE MSBuild

Funkce vlastností řetězce

Všechny hodnoty vlastností sestavení jsou pouze řetězcové hodnoty. K práci s libovolnou hodnotou vlastnosti můžete použít metody řetězce (instance). Můžete například extrahovat název jednotky (první tři znaky) z vlastnosti sestavení, která představuje úplnou cestu pomocí tohoto kódu:

$(ProjectOutputFolder.Substring(0,3))

Statické funkce vlastností

Ve skriptu sestavení máte přístup ke statickým vlastnostem a metodám mnoha systémových tříd. Chcete-li získat hodnotu statické vlastnosti, použijte následující syntaxi, kde Class je název systémové třídy a Property je název vlastnosti.

$([Class]::Property)

Pomocí následujícího kódu můžete například nastavit vlastnost sestavení na aktuální datum a čas.

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

Pokud chcete volat statickou metodu, použijte následující syntaxi, kde Class je název systémové třídy, Method je název metody a (Parameters) je seznam parametrů metody:

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

Pokud chcete například nastavit vlastnost sestavení na nový identifikátor GUID, můžete použít tento skript:

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

Ve funkcích statických vlastností můžete pro tyto systémové třídy použít libovolnou veřejnou statickou metodu nebo vlastnost definovanou v .NET Standard 2.0:

• System.Byte
• System.Char
• System.Convert
• System.datetime
• System.DateTimeOffset (k dispozici ve verzi MSBuild 17.3 a vyšší)
• 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

Kromě toho můžete použít následující statické metody a vlastnosti:

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

<IsWindows>$([System.OperatingSystem]::IsWindows())</IsWindows>

Volání metod instance ve statických vlastnostech

Pokud přistupujete ke statické vlastnosti, která vrací instanci objektu, můžete vyvolat metody instance tohoto objektu. K vyvolání metody instance použijte následující syntaxi, kde Class je název systémové třídy, Property je název vlastnosti, Method je název metody a (Parameters) je seznam parametrů pro metodu:

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

Název třídy musí být plně kvalifikovaný s oborem názvů.

Pomocí následujícího kódu můžete například nastavit vlastnost sestavení na aktuální datum dnes.

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

Funkce vlastností NÁSTROJE MSBuild

K několika statickým metodám v sestavení je možné získat přístup k aritmetické, bitové logické a řídicí podpoře znaků. K těmto metodám se dostanete pomocí následující syntaxe, kde Method je název metody a (Parameters) je seznam parametrů metody.

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

Pokud například chcete sečíst dvě vlastnosti, které mají číselné hodnoty, použijte následující kód.

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

Tady je seznam funkcí vlastností MSBuild:

Vnořené funkce vlastností

Zkombinujte funkce vlastností, které tvoří složitější funkce, jak ukazuje následující příklad:

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

Tento příklad vrátí hodnotu FileAttributes.Archive bit (32 nebo 0) souboru zadaného cestou tempFile. Všimněte si, že výčtové hodnoty dat se v některých kontextech nezobrazují podle názvu. V předchozím příkladu musí být použita číselná hodnota (32). V jiných případech se v závislosti na očekávání volané metody musí použít hodnota výčtu dat. V následujícím příkladu je hodnota RegexOptionsvýčtu .ECMAScript musí být použita, protože číselnou hodnotu nelze převést, protože tato metoda očekává.

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

Metadata se také můžou objevit ve vnořených funkcích vlastností. Další informace najdete v tématu Dávkování.

MSBuild DoesTaskHostExist

Funkce DoesTaskHostExist vlastnosti v nástroji MSBuild vrátí, zda je hostitel úlohy aktuálně nainstalován pro zadané hodnoty modulu runtime a architektury.

Tato funkce vlastnosti má následující syntaxi:

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

MSBuild EnsureTrailingSlash

Funkce EnsureTrailingSlash vlastnosti v nástroji MSBuild přidá koncové lomítko, pokud ještě neexistuje.

Tato funkce vlastnosti má následující syntaxi:

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

MSBuild GetDirectoryNameOfFileAbove

Funkce vlastnosti MSBuild GetDirectoryNameOfFileAbove vyhledá vzhůru adresář obsahující zadaný soubor počínaje zadaným adresářem (včetně). Vrátí úplnou cestu nejbližšího adresáře obsahujícího soubor, pokud je nalezen, jinak prázdný řetězec.

Tato funkce vlastnosti má následující syntaxi:

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

Tento příklad ukazuje, jak importovat nejbližší soubor EnlistmentInfo.props do aktuální složky nebo nad aktuální složkou, pouze pokud se najde shoda:

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

Všimněte si, že tento příklad lze napsat výstižněji pomocí GetPathOfFileAbove funkce:

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

MSBuild GetPathOfFileAbove

Funkce vlastnosti MSBuild GetPathOfFileAbove vyhledá vzhůru adresář obsahující zadaný soubor počínaje zadaným adresářem (včetně). Vrátí úplnou cestu nejbližšího odpovídajícího souboru, pokud je nalezen, jinak prázdný řetězec.

Tato funkce vlastnosti má následující syntaxi:

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

kde file je název souboru, který se má vyhledat, a startingDirectory je volitelným adresářem pro spuštění hledání. Ve výchozím nastavení se hledání spustí ve vlastním adresáři aktuálního souboru.

Tento příklad ukazuje, jak importovat soubor s názvem dir.props do aktuálního adresáře nebo nad aktuálním adresářem, pouze pokud se najde shoda:

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

která je funkčně ekvivalentní

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

Někdy ale potřebujete spustit vyhledávání v nadřazeném adresáři, abyste se vyhnuli porovnávání aktuálního souboru. Tento příklad ukazuje, jak může soubor Directory.Build.props importovat nejbližší soubor Directory.Build.props v přísně vyšší úrovni stromu bez rekurzivního importu samotného:

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

která je funkčně ekvivalentní

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

MSBuild GetRegistryValue

Funkce vlastnosti MSBuild GetRegistryValue vrátí hodnotu klíče registru. Tato funkce přebírá dva argumenty, název klíče a název hodnoty a vrací hodnotu z registru. Pokud nezadáte název hodnoty, vrátí se výchozí hodnota.

Následující příklady ukazují, jak se tato funkce používá:

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

Funkce vlastnosti MSBuild GetRegistryValueFromView získá data systémového registru s ohledem na klíč registru, hodnotu a jedno nebo více seřazených zobrazení registru. Klíč a hodnota se prohledávají v každém zobrazení registru v pořadí, dokud se nenajdou.

Syntaxe této funkce vlastnosti je:

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

64bitový operační systém Windows udržuje klíč registru HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node , který představuje zobrazení registru HKEY_LOCAL_MACHINE\SOFTWARE pro 32bitové aplikace.

Ve výchozím nastavení 32bitová aplikace běžící na WOW64 přistupuje k 32bitovému zobrazení registru a 64bitová aplikace přistupuje k 64bitovému zobrazení registru.

K dispozici jsou následující zobrazení registru:

Například:

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

získá SLRuntimeInstallPath data referenceAssemblies klíč, hledá nejprve v 64bitovém zobrazení registru a pak v 32bitové zobrazení registru.

MSBuild MakeRelative

Funkce vlastnosti MSBuild MakeRelative vrátí relativní cestu druhé cesty vzhledem k první cestě. Každá cesta může být soubor nebo složka.

Tato funkce vlastnosti má následující syntaxi:

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

Následující kód je příkladem této syntaxe.

<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

Funkce vlastnosti MSBuild StableStringHash přijímá argument řetězce a vrací kód hash, který je zaručen stabilní, což znamená, že stejný kód je vždy vrácen pro stejný řetězcový vstup. Vrácená hodnota hash je stejná bez ohledu na to, zda se msBuild nebo dotnet build používá, a je stabilní napříč architekturou platformy, na rozdíl od metody GetHashCode.NET . Není zaručeno, že bude stabilní v různých verzích NÁSTROJE MSBuild.

Tato funkce je dostupná ve verzi MSBuild 16.9.0 nebo novější.

Následující příklad ukazuje, jak se tato funkce používá.

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

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

Z MSBuild verze 17.10.0 tato funkce přijímá druhý volitelný argument, který požaduje algoritmus hash, který se má použít:

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

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

Druhý argument nerozlišuje velká a malá písmena a aktuálně podporuje následující hodnoty:

• Starší verze – zachová stejné chování jako volání funkce bez druhého argumentu. Vrátí 32bitové celé číslo s podobnými vlastnostmi jako string.GetHashCode.
• Fnv1a32bit – vrátí 32bitové celé číslo se znaky 32bit představující hodnotu hash Fowler–Noll–Vo hodnoty hash verze 1a daného řetězce.
• Fnv1a64bit – vrátí 64bitové celé číslo představující hodnotu hash Fowler–Noll–Vo hodnoty hash verze 1a daného řetězce.
• Sha256 – Vrátí nepřefixovaný šestnáctkový řetězec představující hodnotu hash SHA256 daného řetězce.

MSBuild ValueOrDefault

Funkce vlastnosti MSBuild ValueOrDefault vrátí první argument, pokud není null nebo prázdný. Pokud je první argument null nebo prázdný, vrátí funkce druhý argument.

Následující příklad ukazuje, jak se tato funkce používá.

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

Funkce TARGETFramework a TargetPlatform nástroje MSBuild

MSBuild 16.7 a vyšší definují několik funkcí pro zpracování vlastností TargetFramework a TargetPlatform.

Parametr versionPartCount GetTargetFrameworkVersion a GetTargetPlatformVersion má výchozí hodnotu 2.

Následující příklad ukazuje, jak se tyto funkce používají.

<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

Funkce porovnání verzí nástroje MSBuild

MSBuild 16.5 a vyšší definují několik funkcí pro porovnání řetězců, které představují verze.

V těchto metodách jsou verze analyzovány jako System.Version, s následujícími výjimkami:

• Počáteční v nebo V je ignorován, což umožňuje porovnání $(TargetFrameworkVersion)s .

• Vše od prvního řetězce "-" nebo "+" na konec řetězce verze se ignoruje. To umožňuje předávání sémantických verzí (semver), i když pořadí není stejné jako semver. Místo toho specifikátory předběžné verze a metadata sestavení nemají žádnou váhu řazení. To může být užitečné například pro zapnutí funkce >= x.y a jeho zapnutí x.y.z-pre.

• Nezadané části jsou stejné jako části nulové hodnoty. (x == x.0 == x.0.0 == x.0.0.0).

• Prázdné znaky nejsou povoleny v celočíselné komponentě.

• Hlavní verze je platná (3 rovná se 3.0.0.0)

• + není povoleno jako kladné celočíselné komponenty (považuje se za metadata semver a ignorováno).

Funkce podmínek nástroje MSBuild

Exists Funkce a HasTrailingSlash nejsou funkcemi vlastností. Jsou k dispozici pro použití s atributem Condition . Viz podmínky nástroje MSBuild.

Související obsah

• Vlastnosti nástroje MSBuild

• Přehled nástroje MSBuild