Eigenschaftenfunktionen

  • Artikel

Eigenschaftenfunktionen sind Aufrufe von .NET-Methoden, die in MSBuild-Eigenschaftsdefinitionen erscheinen. Im Gegensatz zu Aufgaben können Eigenschaftsfunktionen auch außerhalb von Zielen verwendet werden. Eigenschaftenfunktionen werden immer dann ausgewertet, wenn die Eigenschaften oder Elemente erweitert werden. Daher werden Eigenschaftenfunktionen für Eigenschaften und Elemente außerhalb von Zielen ausgewertet, bevor ein Ziel ausgeführt wird. Für Eigenschaftengruppen und Elementgruppen innerhalb von Zielen werden Eigenschaftenfunktionen ausgewertet, wenn das Ziel ausgewertet wird.

Sie können die Systemzeit lesen, Zeichenfolgen vergleichen, reguläre Ausdrücke abgleichen und viele weitere Aktionen im Buildskript ausführen, ohne MSBuild-Aufgaben zu verwenden. MSBuild versucht, eine Zeichenfolge in eine Zahl und eine Zahl in eine Zeichenfolge zu konvertieren und nimmt je nach Bedarf andere Konvertierungen vor.

Zeichenfolgenwerte, die von Eigenschaftsfunktionen zurückgegeben werden, haben als Sonderzeichen ein Escapezeichen. Wenn Sie möchten, dass der Wert so behandelt wird, als wäre er direkt in der Projektdatei platziert, verwenden Sie $([MSBuild]::Unescape()), um die Sonderzeichen zu entfernen.

Syntax einer Eigenschaftenfunktion

Nachfolgend sehen Sie drei Arten von Eigenschaftenfunktionen; jede Funktion hat eine andere Syntax:

  • Zeichenfolgen-(Instanz-)Eigenschaftenfunktionen
  • Statische Eigenschaftenfunktionen
  • MSBuild-Eigenschaftenfunktionen

Zeichenfolgen-Eigenschaftenfunktionen

Alle Buildeigenschaftswerte sind lediglich Zeichenfolgenwerte. Sie können Zeichenfolgen-(Instanz-)Methoden für beliebige Eigenschaftswerte verwenden. Sie können beispielsweise mithilfe des folgendes Codes den Laufwerksnamen (die ersten drei Buchstaben) aus einer Buildeigenschaft extrahieren, die einen vollständigen Pfad darstellt:

$(ProjectOutputFolder.Substring(0,3))

Statische Eigenschaftenfunktionen

In Ihrem Buildskript können Sie auf die statischen Eigenschaften und Methoden vieler Systemklassen zugreifen. Um den Wert einer statischen Eigenschaft abzurufen, verwenden Sie die folgende Syntax, wobei Class der Name der Systemklasse und Property der Name der Eigenschaft ist.

$([Class]::Property)

Sie können beispielsweise den folgenden Code verwenden, um eine Buildeigenschaft auf das aktuelle Datum und die aktuelle Uhrzeit festzulegen.

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

Um eine statische Methode aufzurufen, verwenden Sie die folgende Syntax, wobei Class der Name der Systemklasse, Method der Name der Methode und (Parameters) die Parameterliste für die Methode ist:

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

Verwenden Sie beispielsweise das folgende Skript, um eine Buildeigenschaft auf eine neu GUID festzulegen:

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

In statischen Eigenschaftenfunktionen können Sie eine beliebige öffentliche statische Methode oder Eigenschaft der folgenden Systemklassen verwenden:

Außerdem können Sie die folgenden statischen Methoden und Eigenschaften verwenden:

System.OperatingSystem-Eigenschaftenfunktionen

Die System.OperatingSystem-Eigenschaftenfunktionen geben Informationen zum Betriebssystem zurück, unter dem MSBuild ausgeführt wird. Wenn Ihr Projekt beispielsweise auf Linux ausgerichtet ist und Sie es unter macOS erstellen, geben die Eigenschaftenfunktionen Informationen zu macOS zurück.

In MSBuild, das unter .NET (dotnet build) ausgeführt wird, können alle statischen Methoden der System.OperatingSystem-Klasse als statische Eigenschaftenfunktionen aufgerufen werden.

In MSBuild, das unter .NET Framework (MSBuild.exe) ausgeführt wird, können nur die folgenden Methoden der System.OperatingSystem-Klasse als statische Eigenschaftenfunktionen aufgerufen werden. MSBuild implementiert sie intern, da System.OperatingSystem sie nicht unter .NET Framework definiert. Methoden für Betriebssysteme, für die kein .NET SDK vorhanden ist, z. B. System.OperatingSystem::IsTvOS, können nicht aufgerufen werden.

Im folgenden Beispiel wird die Verwendung dieser Eigenschaftenfunktionen veranschaulicht.

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

Aufrufen von Instanzmethoden für statische Eigenschaften

Wenn Sie auf eine statische Eigenschaft zugreifen, die eine Objektinstanz zurückgibt, können Sie die Instanzmethoden dieses Objekts aufrufen. Um eine statische Methode aufzurufen, verwenden Sie die folgende Syntax, wobei Class der Name der Systemklasse, Property der Name der Eigenschaft, Method der Name der Methode und (Parameters) die Parameterliste für die Methode ist:

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

Der Name der Klasse muss mit dem Namespace vollqualifiziert sein.

Sie können beispielsweise den folgenden Code verwenden, um eine Buildeigenschaft auf das heutige Datum festzulegen.

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

MSBuild-Eigenschaftenfunktionen

In Ihrem Build kann auf mehrere statische Methoden zugegriffen werden, um Unterstützung für arithmetische, bitweise logische und Escapezeichen bereitzustellen. Sie greifen auf diese Methoden mithilfe der folgenden Syntax zu, wobei Method der Name der Methode und (Parameters) die Parameterliste für die Methode ist.

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

Um beispielsweise zwei Eigenschaften mit numerischen Werten zu addieren, verwenden Sie den folgenden Code.

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

Nachfolgend finden Sie eine Liste mit MSBuild-Eigenschaftenfunktionen:

Funktionssignatur Beschreibung
double Add(double a, double b) Addiert zwei double-Werte.
long Add(long a, long b) Addiert zwei long-Werte.
double Subtract(double a, double b) Subtrahiert zwei double-Werte.
long Subtract(long a, long b) Subtrahiert zwei long-Werte.
double Multiply(double a, double b) Multipliziert zwei double-Werte.
long Multiply(long a, long b) Multipliziert zwei long-Werte.
double Divide(double a, double b) Dividiert zwei double-Werte.
long Divide(long a, long b) Dividiert zwei long-Werte.
double Modulo(double a, double b) Modulo-Berechnung für zwei double-Werte.
long Modulo(long a, long b) Modulo-Berechnung für zwei long-Werte.
string Escape(string unescaped) Setzt gemäß den MSBuild-Escape-Regeln ein Escapezeichen vor die Zeichenfolge.
string Unescape(string escaped) Entfernt gemäß den MSBuild-Escape-Regeln ein Escapezeichen vor der Zeichenfolge.
int BitwiseOr(int first, int second) Führt einen bitweisen OR-Vorgang für das erste und zweite Element aus (first | second).
int BitwiseAnd(int first, int second) Führt einen bitweisen AND-Vorgang für das erste und zweite Element aus (first & second).
int BitwiseXor(int first, int second) Führt einen bitweisen XOR-Vorgang für das erste und zweite Element aus (first ^ second).
int BitwiseNot(int first) Führt einen bitweisen NOT-Vorgang aus (~first).
bool IsOsPlatform(string platformString) Gibt an, ob die aktuelle Betriebssystemplattform platformString ist. platformString muss ein Mitglied von OSPlatform sein.
bool IsOSUnixLike() „TRUE“, wenn das aktuelle Betriebssystem ein Unix-System ist.
string NormalizePath(params string[] path) Ruft den vereinheitlichten vollständigen Pfad des bereitgestellten Pfads ab und stellt sicher, dass dieser die richtigen Verzeichnistrennzeichen für das aktuelle Betriebssystem enthält.
string NormalizeDirectory(params string[] path) Ruft den vereinheitlichten vollständigen Pfad des bereitgestellten Verzeichnisses ab und stellt sicher, dass dieser die richtigen Verzeichnistrennzeichen für das aktuelle Betriebssystem und einen nachstehenden Schrägstrich enthält.
string EnsureTrailingSlash(string path) Wenn der angegebene Pfad keinen nachgestellten Schrägstrich besitzt, fügen Sie einen hinzu. Wenn der Pfad eine leere Zeichenfolge ist, ändern Sie diesen nicht.
string GetPathOfFileAbove(string file, string startingDirectory) Sucht in der Verzeichnisstruktur am und oberhalb des Speicherorts der aktuellen Builddatei oder basierend auf startingDirectory (sofern angegeben) nach einer Datei und gibt den vollständigen Pfad zu dieser Datei zurück.
string GetDirectoryNameOfFileAbove(string startingDirectory, string fileName) Sucht entweder im angegebenen Verzeichnis oder an einem Speicherort in der Verzeichnisstruktur oberhalb dieses Verzeichnisses nach dem Verzeichnis einer Datei und gibt dieses zurück.
string MakeRelative(string basePath, string path) Macht path relativ zu basePath. Bei basePath muss es sich um ein absolutes Verzeichnis handeln. Wenn path nicht relativ gemacht werden kann, wird dieses wörtlich zurückgegeben. Vergleichbar zu Uri.MakeRelativeUri.
string ValueOrDefault(string conditionValue, string defaultValue) Gibt die Zeichenfolge im defaultValue-Parameter nur zurück, wenn der conditionValue-Parameter leer ist. Andernfalls wird der Wert conditionValue zurückgegeben.
string ConvertToBase64(string toEncode) Gibt die Zeichenfolge zurück, nachdem alle Bytes in Base64 konvertiert wurden (alphanumerische Zeichen plus + und /), die auf ein oder zwei = endet.
string ConvertFromBase64(string toDecode) Gibt die Zeichenfolge nach der Konvertierung aus Base64 zurück (alphanumerische Zeichen plus + und /), die auf ein oder zwei = endet.

Geschachtelte Eigenschaftenfunktionen

Sie können Eigenschaftenfunktionen kombinieren, um komplexere Funktionen zu erstellen, wie das folgende Beispiel zeigt:

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

In diesem Beispiel wird der Wert des FileAttributes.-BitsArchive (32 oder 0) der Datei zurückgegeben, die durch den Pfad angegeben wird tempFile. Beachten Sie, dass aufgezählte Datenwerte in einigen Kontexten nicht anhand des Namens angezeigt werden können. Im vorherigen Beispiel muss stattdessen der numerische Wert (32) verwendet werden. In anderen Fällen muss abhängig von den Erwartungen der aufgerufenen Methode der Enumerationsdatenwert verwendet werden. Im folgenden Beispiel muss der Enumerationswert RegexOptions.ECMAScript muss verwendet werden, weil ein numerischer Wert nicht den Erwartungen dieser Methode entsprechend konvertiert werden kann.

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

Metadaten können auch in geschachtelten Eigenschaftenfunktionen angezeigt werden. Weitere Informationen finden Sie unter MSBuild Batching (Batchverarbeitung).

MSBuild DoesTaskHostExist

Die DoesTaskHostExist-Eigenschaftenfunktion in MSBuild gibt zurück, ob derzeit ein Aufgabenhost für die angegebenen Laufzeit- und Architekturwerte installiert wird.

Diese Eigenschaftenfunktion hat die folgende Syntax:

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

MSBuild EnsureTrailingSlash

Die EnsureTrailingSlash-Eigenschaftenfunktion in MSBuild fügt einen nachgestellten Schrägstrich hinzu, wenn noch keiner vorhanden ist.

Diese Eigenschaftenfunktion hat die folgende Syntax:

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

MSBuild GetDirectoryNameOfFileAbove

Die MSBuild-Eigenschaftenfunktion GetDirectoryNameOfFileAbove sucht aufwärts nach einem Verzeichnis, das die angegebene Datei enthält. Sie beginnt damit im angegebenen Verzeichnis (wird ebenfalls durchsucht). Sie gibt den vollständigen Pfad des nächstgelegenen Verzeichnisses zurück, das die Datei enthält, sofern es gefunden wird. Andernfalls gibt sie eine leere Zeichenfolge zurück.

Diese Eigenschaftenfunktion hat die folgende Syntax:

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

In diesem Beispiel wird gezeigt, wie die nächste EnlistmentInfo.props-Datei nur dann in oder oberhalb des aktuellen Ordners importiert wird, wenn eine Übereinstimmung gefunden wird:

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

Beachten Sie, dass dieses Beispiel mit der GetPathOfFileAbove-Funktion präziser geschrieben werden könnte:

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

MSBuild GetPathOfFileAbove

Die MSBuild-Eigenschaftenfunktion GetPathOfFileAbove sucht aufwärts nach einem Verzeichnis, das die angegebene Datei enthält. Sie beginnt damit im angegebenen Verzeichnis (wird ebenfalls durchsucht). Sie gibt den vollständigen Pfad der nächstgelegenen übereinstimmenden Datei zurück, wenn diese gefunden wird. Andernfalls gibt sie eine leere Zeichenfolge zurück.

Diese Eigenschaftenfunktion hat die folgende Syntax:

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

Dabei ist file der Name der zu suchenden Datei und startingDirectory ein optionales Verzeichnis, in dem die Suche gestartet wird. Standardmäßig wird die Suche im eigenen Verzeichnis der aktuellen Datei gestartet.

In diesem Beispiel wird gezeigt, wie eine Datei namens dir.props nur dann in oder oberhalb des aktuellen Verzeichnisses importiert wird, wenn eine Übereinstimmung gefunden wird:

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

Dies ist funktionell äquivalent zu:

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

In bestimmten Situationen müssen Sie die Suche jedoch im übergeordneten Verzeichnis starten, um eine Übereinstimmung mit der aktuellen Datei zu vermeiden. Dieses Beispiel zeigt, wie eine Directory.Build.props-Datei die nächstgelegene Directory.Build.props-Datei in eine strikt höhere Strukturebene importieren kann, ohne sich selbst rekursiv zu importieren:

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

Dies ist funktionell äquivalent zu:

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

MSBuild GetRegistryValue

Die GetRegistryValue-Eigenschaftenfunktion in MSBuild gibt den Wert eines Registrierungsschlüssels zurück. Diese Funktion weist zwei Argumente auf, den Schlüsselnamen und den Wertnamen, und gibt den Wert aus der Registrierung zurück. Wenn Sie keinen Wertnamen angeben, wird der Standardwert zurückgegeben.

In den folgenden Beispielen wird veranschaulicht, wie diese Funktion verwendet wird:

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

Warnung

In der .NET SDK-Version von MSBuild (dotnet build) wird diese Funktion nicht unterstützt.

MSBuild GetRegistryValueFromView

Die GetRegistryValueFromView-Eigenschaftenfunktion in MSBuild ruft Systemregistrierungsdaten anhand des Registrierungsschlüssels, des Werts und einer oder mehrerer geordneter Registrierungsansichten ab. Der Wert und der Schlüssel werden der Reihe nach in jeder Registrierungsansicht gesucht, bis sie gefunden wurden.

Die Syntax für diese Eigenschaftenfunktion ist wie folgt:

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

Das Windows-Betriebssystem mit 64 Bit speichert einen HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node-Registrierungsschlüssel, der eine HKEY_LOCAL_MACHINE\SOFTWARE-Registrierungsansicht für 32-Bit-Anwendungen darstellt.

Eine 32-Bit-Anwendung, die unter WOW64 ausgeführt wird, greift standardmäßig auf die 32-Bit-Registrierungsansicht zu, und eine 64-Bit-Anwendung greift auf die 64-Bit-Registrierungsansicht zu.

Die folgenden Registrierungsansichten sind verfügbar:

Registrierungsansicht Definition
RegistryView.Registry32 Die Registrierungsansicht für 32-Bit-Anwendungen.
RegistryView.Registry64 Die Registrierungsansicht für 64-Bit-Anwendungen.
RegistryView.Default Die Registrierungsansicht, die mit dem Prozess übereinstimmt, auf dem die Anwendung ausgeführt wird.

Nachfolgend finden Sie ein Beispiel:

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

ruft die SLRuntimeInstallPath-Daten des ReferenceAssemblies-Schlüssels ab und sucht zuerst in der 64-Bit-Registrierungsansicht und dann in der 32-Bit-Registrierungsansicht.

Warnung

In der .NET SDK-Version von MSBuild (dotnet build) wird diese Funktion nicht unterstützt.

MSBuild MakeRelative

Die MakeRelative-Eigenschaftenfunktion in MSBuild gibt den relativen Pfad des zweiten Pfads relativ zum ersten Pfad an. Jeder Pfad kann eine Datei oder ein Ordner sein.

Diese Eigenschaftenfunktion hat die folgende Syntax:

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

Der folgende Code veranschaulicht diese Syntax beispielhaft.

<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

Die MSBuild-Eigenschaftenfunktion StableStringHash akzeptiert ein Zeichenfolgenargument und gibt einen Hashcode zurück, der garantiert stabil ist. Das bedeutet, dass für dieselbe Zeichenfolgeneingabe immer derselbe Code zurückgegeben wird. Der zurückgegebene Hash ist identisch, unabhängig davon, ob MSBuild oder dotnet build verwendet wird, und ist im Gegensatz zur .NET-Methode GetHashCode in der gesamten Plattformarchitektur stabil. Die Stabilität über verschiedene MSBuild-Versionen hinweg kann nicht garantiert werden.

Diese Funktion ist in MSBuild 16.9.0 oder höher verfügbar.

In dem folgenden Beispiel wird veranschaulicht, wie diese Funktion verwendet wird.

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

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

Ab MSBuild Version 17.10.0 akzeptiert diese Funktion ein zweites, optionales Argument, das den zu verwendenden Hashing-Algorithmus anfordert:

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

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

Das zweite Argument ist unabhängig von der Groß- und Kleinschreibung und unterstützt derzeit folgende Werte:

  • Legacy – behält das gleiche Verhalten wie der Aufruf der Funktion ohne das zweite Argument. Gibt eine vorzeichenbehaftete 32-Bit-Ganzzahl mit ähnlichen Eigenschaften wie string.GetHashCode zurück.
  • Fnv1a32bit – Gibt eine vorzeichenbehaftete 32-Bit-Ganzzahl zurück, die einen Fowler-Noll-Vo-Hash der Version '1a'-Hash des angegebenen Strings darstellt.
  • Fnv1a64bit – Gibt eine vorzeichenbehaftete 64-Bit-Ganzzahl zurück, die einen Fowler-Noll-Vo-Hash der Version '1a'-Hash des angegebenen Strings darstellt.
  • Sha256 – Gibt einen Hex-String ohne Präfix zurück, der einen SHA256-Hash des angegebenen Strings darstellt.

MSBuild ValueOrDefault

Die ValueOrDefault-Eigenschaftenfunktion in MSBuild gibt das erste Argumente zurück, sofern dieses nicht Null oder leer ist. Wenn das erste Argument Null oder leer ist, gibt die Funktion das zweite Argument zurück.

In dem folgenden Beispiel wird veranschaulicht, wie diese Funktion verwendet wird.

<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-Funktionen „TargetFramework“ und „TargetPlatform“

MSBuild 16.7 und höher definiert mehrere Funktionen für die Verarbeitung von TargetFramework- und TargetPlatform-Eigenschaften.

Funktionssignatur Beschreibung
GetTargetFrameworkIdentifier(string targetFramework) Analysiert TargetFrameworkIdentifier aus TargetFramework
GetTargetFrameworkVersion(string targetFramework, int versionPartCount) Analysiert TargetFrameworkVersion aus TargetFramework
GetTargetPlatformIdentifier(string targetFramework) Analysiert TargetPlatformIdentifier aus TargetFramework
GetTargetPlatformVersion(string targetFramework, int versionPartCount) Analysiert TargetPlatformVersion aus TargetFramework
IsTargetFrameworkCompatible(string targetFrameworkTarget, string targetFrameworkCandidate) Gibt „True“ zurück, wenn das Kandidatenzielframework (zweites Argument) mit dem Zielframework kompatibel ist, das durch das erste Argument angegeben wird, andernfalls „False“.

Der Wert des versionPartCount-Parameters von GetTargetFrameworkVersion und GetTargetPlatformVersion lautet standardmäßig 2.

Im folgenden Beispiel wird gezeigt, wie diese Funktionen verwendet werden.

<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

Funktionen für Versionsvergleiche in MSBuild

In MSBuild 16.5 und höher sind einige Funktionen definiert, mit denen Zeichenfolgen verglichen werden können, die für Versionen stehen.

Hinweis

Vergleichsoperatoren in Bedingungen können Zeichenfolgen vergleichen, die als System.Version-Objekte analysiert werden können. Vergleiche können aber auch zu unerwarteten Ergebnissen führen. Die Eigenschaftsfunktionen sollten bevorzugt verwendet werden.

Funktionssignatur Beschreibung
VersionEquals(string a, string b) true wird zurückgegeben, wenn die Versionen a und b entsprechend der untenstehenden Regeln äquivalent sind.
VersionGreaterThan(string a, string b) true wird zurückgegeben, wenn die Version a entsprechend der untenstehenden Regeln höher ist als b.
VersionGreaterThanOrEquals(string a, string b) true wird zurückgegeben, wenn die Version a entsprechend der untenstehenden Regeln höher oder gleich b ist.
VersionLessThan(string a, string b) true wird zurückgegeben, wenn die Version a entsprechend der untenstehenden Regeln niedriger als b ist.
VersionLessThanOrEquals(string a, string b) true wird zurückgegeben, wenn die Version a entsprechend der untenstehenden Regeln niedriger oder gleich b ist.
VersionNotEquals(string a, string b) false wird zurückgegeben, wenn die Versionen a und b entsprechend der untenstehenden Regeln äquivalent sind.

In diesen Methoden werden Versionen wie System.Version analysiert. Dabei gelten die folgenden Ausnahmen:

  • Ein voranstehendes v oder V wird ignoriert, was Vergleiche mit $(TargetFrameworkVersion) ermöglicht.

  • Alle Zeichen ab dem ersten „-“ oder „+“ bis zum Ende der Versionszeichenfolge werden ignoriert. So können semantische Versionen (SemVer) übergeben werden, obwohl die Reihenfolge nicht identisch mit SemVer ist. Stattdessen wirken sich Spezifizierer für vorab releaste Versionen und Buildmetadaten bei der Sortierung nicht aus. Dies kann nützlich sein, beispielsweise um ein Feature so für >= x.y zu aktivieren, dass es für x.y.z-pre gültig ist.

  • Nicht spezifizierte Teile gelten wie Teile mit 0-Werten. (x == x.0 == x.0.0 == x.0.0.0).

  • Leerzeichen sind für Integerkomponenten nicht zulässig.

  • Nur die Hauptversion ist gültig (3 ist gleich 3.0.0.0).

  • + ist als Pluszeichen für Integerkomponenten nicht zulässig und wird wie SemVer-Metadaten behandelt und ignoriert.

Tipp

Bei Vergleichen von TargetFramework-Eigenschaften sollte generell IsTargetFrameworkCompatible verwendet werden, anstatt Versionen zu extrahieren und zu vergleichen. So können Werte für TargetFramework verglichen werden, die eine Variation bei TargetFrameworkIdentifier aufweisen, sowie die Version.

MSBuild-Bedingungsfunktionen

Die Funktionen Exists und HasTrailingSlash sind keine Eigenschaftenfunktionen. Sie können mit dem Condition-Attribut verwendet werden. Weitere Informationen finden Sie unter MSBuild-Bedingungen.

Zugehöriger Inhalt