Egenskapsfunktioner

Egenskapsfunktioner är anrop till .NET-metoder som visas i MSBuild-egenskapsdefinitioner. Du använder dem vanligtvis för att konstruera egenskapsdefinitioner som kräver mer komplex logik.

Till skillnad från uppgifter kan egenskapsfunktioner användas utanför mål. Egenskapsfunktioner utvärderas när egenskaperna eller objekten expanderas. För egenskaper och objekt utanför alla mål utvärderas egenskapsfunktioner därför innan några mål körs. För egenskapsgrupper och objektgrupper inuti mål utvärderas egenskapsfunktioner när målet körs.

Utan att använda MSBuild-uppgifter kan du läsa systemtiden, jämföra strängar, matcha reguljära uttryck och utföra andra åtgärder i byggskriptet. MSBuild försöker konvertera sträng till tal och tal till sträng och göra andra konverteringar efter behov.

Strängvärden som returneras från egenskapsfunktioner har undantagna specialtecken . Om du vill att värdet ska behandlas som om det lades direkt i projektfilen använder $([MSBuild]::Unescape()) du för att ta bort specialtecken.

Syntax för egenskapsfunktionen

Det finns tre typer av egenskapsfunktioner. varje typ har en annan syntax:

• Egenskapsfunktioner för sträng (instans)
• Statiska egenskapsfunktioner
• MSBuild-egenskapsfunktioner

Funktioner för strängegenskap

Alla byggegenskapsvärden är bara strängvärden. Du kan använda strängmetoder (instans) för att arbeta med valfritt egenskapsvärde. Du kan till exempel extrahera enhetsnamnet (de tre första tecknen) från en byggparameter som representerar en fullständig sökväg med hjälp av den här koden:

$(ProjectOutputFolder.Substring(0,3))

Statiska egenskapsfunktioner

I byggskriptet kan du komma åt statiska egenskaper och metoder för många systemklasser. Om du vill hämta värdet för en statisk egenskap använder du följande syntax, där Class är namnet på systemklassen och Property är namnet på egenskapen.

$([Class]::Property)

Du kan till exempel använda följande kod för att ange en byggegenskap till aktuellt datum och tid.

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

Om du vill anropa en statisk metod använder du följande syntax, där Class är namnet på systemklassen, Method är namnet på metoden och (Parameters) är parameterlistan för metoden:

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

Om du till exempel vill ange en byggegenskap till ett nytt GUID kan du använda det här skriptet:

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

För överlagrade metoder försöker MSBuild hitta en metod med matchande parametrar.

I MSBuild 17.14 och senare kan du använda parametersyntaxen out _ för att ange en out parameter. Se Referensparametrar. Parametervärdet out ignoreras. Till exempel:

<IsInteger>$([System.Int32]::TryParse("123", out _))</IsInteger>

Egenskapen IsInteger är true om indata parsas som ett heltal, men det parsade värdet ignoreras.

I statiska egenskapsfunktioner kan du använda valfri offentlig statisk metod eller egenskap som definierats i .NET Standard 2.0 för dessa systemklasser:

• System.Byte
• System.Char
• System.Convert
• System.DateTime
• System.DateTimeOffset (tillgängligt i MSBuild 17.3 och senare)
• 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

Dessutom kan du använda följande statiska metoder och egenskaper:

• 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
• System.Globalization.CultureInfo::GetCultureInfo
• System.Globalization.CultureInfo::new
• System.Globalization.CultureInfo::CurrentUICulture

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

Anropa instansmetoder för statiska egenskaper

Om du har åtkomst till en statisk egenskap som returnerar en objektinstans kan du anropa instansmetoderna för objektet. Om du vill anropa en instansmetod använder du följande syntax, där Class är namnet på systemklassen, Property är namnet på egenskapen, Method är namnet på metoden och (Parameters) är parameterlistan för metoden:

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

Namnet på klassen måste vara fullständigt kvalificerat med namespace.

Du kan till exempel använda följande kod för att ange en kompileringsegenskap till dagens datum idag.

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

MSBuild-egenskapsfunktioner

Flera statiska metoder i din byggprocess kan nås för att ge stöd för aritmetik, bitvis logiska operationer och escape-tecken. Du kommer åt dessa metoder med hjälp av följande syntax, där Method är namnet på metoden och (Parameters) är parameterlistan för metoden.

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

Om du till exempel vill lägga till två egenskaper som har numeriska värden använder du följande kod.

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

Här är en lista över MSBuild-egenskapsfunktioner:

Kapslade egenskapsfunktioner

Du kan kombinera egenskapsfunktioner för att skapa mer komplexa funktioner, som följande exempel visar:

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

Det här exemplet returnerar värdet för FileAttributes. Archive biten (32 eller 0) av filen som anges av sökvägen tempFile. Observera att uppräknade datavärden inte kan visas med namn i vissa kontexter. I föregående exempel måste det numeriska värdet (32) användas i stället. I andra fall måste enum-värdet användas, beroende på den anropade metodens förväntningar. I följande exempel är uppräkningsvärdet RegexOptions. ECMAScript måste användas eftersom ett numeriskt värde inte kan konverteras som den här metoden förväntar sig.

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

Metadata kan också visas i kapslade egenskapsfunktioner. Mer information finns i Batching.

MSBuild KontrollerarOmUppgiftsmiljöFinns

Egenskapsfunktionen DoesTaskHostExist i MSBuild anger huruvida en uppgiftshanterare för närvarande är installerad för den angivna körningen och arkitekturen.

Den här egenskapsfunktionen har följande syntax:

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

MSBuild EnsureTrailingSlash

Egenskapsfunktionen EnsureTrailingSlash i MSBuild lägger till ett avslutande snedstreck om det inte redan finns något.

Den här egenskapsfunktionen har följande syntax:

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

MSBuild HämtaKatalognamnFörFilOvan

Egenskapsfunktionen MSBuild GetDirectoryNameOfFileAbove söker uppåt efter en katalog som innehåller den angivna filen, med början i (och inklusive) den angivna katalogen. Den returnerar den fullständiga sökvägen till den närmaste katalogen som innehåller filen om den hittas, annars en tom sträng.

Den här egenskapsfunktionen har följande syntax:

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

Det här exemplet visar hur du importerar den närmaste Filen EnlistmentInfo.props i eller ovanför den aktuella mappen, endast om en matchning hittas:

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

Det här exemplet kan skrivas mer kortfattat med hjälp GetPathOfFileAbove av funktionen i stället:

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

"MSBuild GetPathOfFileAbove"

Egenskapsfunktionen MSBuild GetPathOfFileAbove söker uppåt efter en katalog som innehåller den angivna filen, med början i (och inklusive) den angivna katalogen. Den returnerar den fullständiga sökvägen till den närmaste matchande filen om den hittas, annars en tom sträng.

Den här egenskapsfunktionen har följande syntax:

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

där file är namnet på filen som ska sökas efter och startingDirectory är en valfri katalog för att starta sökningen i. Som standard startar sökningen i den aktuella filens egen katalog.

Det här exemplet visar hur du importerar en fil med namnet dir.props i eller ovanför den aktuella katalogen, endast om en matchning hittas:

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

som är funktionellt likvärdig med

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

Ibland måste du dock starta sökningen i den överordnade katalogen för att undvika att matcha den aktuella filen. Det här exemplet visar hur en Directory.Build.props-fil kan importera närmaste Directory.Build.props-fil i en strikt högre nivå i trädet, utan att rekursivt importera sig själv:

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

som är funktionellt likvärdig med

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

MSBuild HämtaRegistervärde

Egenskapsfunktionen MSBuild GetRegistryValue returnerar värdet för en registernyckel. Den här funktionen tar två argument, nyckelnamnet och värdenamnet, och returnerar värdet från registret. Om du inte anger något värdenamn returneras standardvärdet.

Följande exempel visar hur den här funktionen används:

$([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 HämtaRegistervärdeFrånVy

Egenskapsfunktionen MSBuild GetRegistryValueFromView hämtar systemregisterdata givet registernyckeln, värdet och en eller flera ordnade registervyer. Nyckeln och värdet genomsöks i varje registervy i ordning tills de hittas.

Syntaxen för den här egenskapsfunktionen är:

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

Windows 64-bitars operativsystem har en HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node registernyckel som visar en HKEY_LOCAL_MACHINE\SOFTWARE registervy för 32-bitarsprogram.

Som standard har ett 32-bitarsprogram som körs på WOW64 åtkomst till 32-bitars registervyn och ett 64-bitarsprogram får åtkomst till 64-bitars registervyn.

Följande registervyer är tillgängliga:

Följande är ett exempel.

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

Föregående kod hämtar SLRuntimeInstallPath-data för ReferenceAssemblies-nyckeln , letar först i 64-bitars registervyn och sedan i 32-bitars registervyn.

MSBuild MakeRelative

Egenskapsfunktionen MSBuild MakeRelative returnerar den relativa sökvägen för den andra sökvägen i förhållande till den första sökvägen. Varje sökväg kan vara en fil eller mapp.

Den här egenskapsfunktionen har följande syntax:

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

Följande kod är ett exempel på den här syntaxen.

<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

Egenskapsfunktionen MSBuild StableStringHash accepterar ett strängargument och returnerar en hash-kod som garanterat är stabil, vilket innebär att samma kod alltid returneras för samma strängindata. Den returnerade hashen är densamma oavsett om MSBuild eller dotnet build används och är stabil i plattformsarkitekturen, till skillnad från .NET-metoden GetHashCode. Den är inte garanterad att vara stabil i olika MSBuild-versioner.

Den här funktionen är tillgänglig i MSBuild 16.9.0 eller senare.

I följande exempel visas hur den här funktionen används.

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

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

Med MSBuild version 17.10 och senare accepterar den här funktionen det andra, valfria argumentet som begär att hash-algoritmen ska användas:

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

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

Det andra argumentet är skiftlägesokänsligt och stöder för närvarande följande värden:

• Arvet – behåller samma beteende som att anropa funktionen utan det andra argumentet. Returnerar signerat 32-bitars heltal med liknande egenskaper som string.GetHashCode.
• Fnv1a32bit – Returnerar signerat 32-bitars heltal som representerar en Fowler–Noll-Vo-hash av version "1a" hash av den angivna strängen.
• Fnv1a64bit – Returnerar signerat 64-bitars heltal som representerar en Fowler–Noll-Vo-hash av version "1a" hash av den angivna strängen.
• Sha256 – Returnerar en oförberedd hexsträng som representerar en SHA256-hash för den angivna strängen.

MSBuild ValueOrDefault

Egenskapsfunktionen MSBuild ValueOrDefault returnerar det första argumentet, såvida det inte är null eller tomt. Om det första argumentet är null eller tomt returnerar funktionen det andra argumentet.

I följande exempel visas hur den här funktionen används.

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

FUNKTIONERNA MSBuild TargetFramework och TargetPlatform

MSBuild 16.7 och senare definierar flera funktioner för hantering av targetframework- och TargetPlatform-egenskaper.

Parametern versionPartCountGetTargetFrameworkVersion för och GetTargetPlatformVersion har standardvärdet 2.

I följande exempel visas hur dessa funktioner används.

<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-funktioner för versionsjämförelse

MSBuild 16.5 och senare definierar flera funktioner för att jämföra strängar som representerar versioner.

I dessa metoder parsas versioner som System.Version, med följande undantag:

• Inledande v eller V ignoreras, vilket gör det möjligt att $(TargetFrameworkVersion)jämföra med .

• Allt från den första "-" eller "+" till slutet av versionssträngen ignoreras. Detta gör det möjligt att skicka in semantiska versioner (semver), även om ordningen inte är samma som semver. I stället har förhandsversionsspecificerare och kompileringsmetadata ingen sorteringsvikt. Detta kan till exempel vara användbart för att aktivera en funktion för >= x.y och så att den aktiveras på x.y.z-pre.

• Ospecificerade delar är samma som nollvärdesdelar. (x == x.0 == x.0.0 == x.0.0.0)

• Mellanslag tillåts inte i heltalskomponenter.

• Huvudversionen är endast giltig (3 är lika med 3.0.0.0)

• + tillåts inte som positiva tecken i heltalskomponenter (det behandlas som semvermetadata och ignoreras)

MSBuild-villkorsfunktioner

Funktionerna Exists och HasTrailingSlash är inte egenskapsfunktioner. De är tillgängliga för användning med attributet Condition . Se MSBuild-villkor.

Relaterat innehåll

• MSBuild-egenskaper

• MSBuild-översikt