Freigeben über

Eigenschaftenfunktionen

Eigenschaftsfunktionen sind Aufrufe von .NET-Methoden, die in MSBuild-Eigenschaftsdefinitionen angezeigt werden. In der Regel verwenden Sie sie, um Eigenschaftsdefinitionen zu erstellen, die komplexere Logik erfordern.

Im Gegensatz zu Aufgaben können Eigenschaftsfunktionen außerhalb von Zielen verwendet werden. Eigenschaftsfunktionen werden immer ausgewertet, wenn die Eigenschaften oder Elemente erweitert werden. Für Eigenschaften und Elemente außerhalb von Zielen werden Eigenschaftenfunktionen also vor jeder Ausführung des Ziels ausgewertet. Bei Eigenschaftengruppen und Elementgruppen innerhalb von Zielen werden Eigenschaftsfunktionen ausgewertet, wenn das Ziel ausgeführt wird.

Ohne Verwendung von MSBuild-Aufgaben können Sie die Systemzeit lesen, Zeichenfolgen vergleichen, reguläre Ausdrücke abgleichen und andere Aktionen in Ihrem Buildskript ausführen. MSBuild versucht, Zeichenfolgen in Zahlen und Zahlen in Zeichenfolgen umzuwandeln und andere Umwandlungen bei Bedarf vorzunehmen.

Zeichenfolgenwerte, die von Eigenschaftsfunktionen zurückgegeben werden, haben als Sonderzeichen ein Escapezeichen. Wenn der Wert so behandelt werden soll, als ob er direkt in die Projektdatei gesetzt wurde, verwenden Sie $([MSBuild]::Unescape()), um die Sonderzeichen aufzuheben.

Syntax einer Eigenschaftenfunktion

Es gibt drei Arten von Eigenschaftenfunktionen; jede Art weist eine andere Syntax auf:

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

Zeichenfolgen-Eigenschaftenfunktionen

Alle Buildeigenschaftswerte sind lediglich Zeichenfolgenwerte. Sie können Instanz-Zeichenfolgenmethoden verwenden, um auf einem beliebigen Eigenschaftswert zu operieren. Sie können z. B. den Laufwerknamen (die ersten drei Zeichen) aus einer Buildeigenschaft extrahieren, die einen vollständigen Pfad darstellt, indem Sie diesen Code verwenden:

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

Verwenden Sie zum Aufrufen einer statischen Methode die folgende Syntax, wobei Class der Name der Systemklasse der Name der Methode ist, Method und (Parameters) ist die Parameterliste für die Methode:

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

Um beispielsweise eine Buildeigenschaft auf eine neue GUID festzulegen, können Sie dieses Skript verwenden:

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

Bei überladenen Methoden versucht MSBuild, eine Methode mit übereinstimmenden Parametern zu finden.

In MSBuild 17.14 und höher können Sie die Parametersyntax out _ verwenden, um einen out Parameter anzugeben. Siehe Referenzparameter. Der out Parameterwert wird ignoriert. Beispiel:

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

Die Eigenschaft IsInteger ist true , wenn die Eingabe erfolgreich als ganze Zahl analysiert wird, der analysierte Wert wird jedoch ignoriert.

In statischen Eigenschaftenfunktionen können Sie eine beliebige öffentliche statische Methode oder Eigenschaft verwenden, die in .NET Standard 2.0 für diese Systemklassen definiert ist:

Hinweis

Methoden und Eigenschaften, die in .NET Standard 2.0 nicht definiert sind, können möglicherweise verfügbar sein, wenn Sie MSBuild in einer Umgebung verwenden, die sie unterstützt, aber es kann nicht garantiert werden, dass sie in allen Situationen verfügbar sind. Aus Kompatibilitätsgründen werden sie am besten vermieden.

Darüber hinaus können Sie die folgenden statischen Methoden und Eigenschaften verwenden:

System.OperatingSystem-Eigenschaftenfunktionen

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

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

In MSBuild, das auf .NET Framework (MSBuild.exe) ausgeführt wird, können nur die folgenden Methoden System.OperatingSystem als statische Eigenschaftsfunktionen 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, sind nicht aufrufbar, z. B. System.OperatingSystem::IsTvOS.

Das folgende Beispiel zeigt die Verwendung dieser Eigenschaftsfunktionen.

<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. Verwenden Sie zum Aufrufen einer Instanzmethode 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 vollständig qualifiziert sein.

Sie können z. B. den folgenden Code verwenden, um eine Buildeigenschaft auf das aktuelle Datum heute festzulegen.

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

MSBuild-Eigenschaftsfunktionen

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

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

Wenn Sie beispielsweise zwei Eigenschaften mit numerischen Werten hinzufügen möchten, verwenden Sie den folgenden Code.

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

Hier ist eine Liste der MSBuild-Eigenschaftsfunktionen:

Funktionssignatur BESCHREIBUNG
double Add(double a, double b) Addiert zwei double-Werte.
long Add(long a, long b) Addiert zwei long-Werte.
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).
string CheckFeatureAvailability(string featureName) Gibt den Featurenamen als Zeichenfolge zurück, wenn und nur, wenn das angegebene Feature in dieser Version von MSBuild unterstützt wird.
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 von Base64 (alphanumerische Zeichen plus + und /) zurück, endend mit einem oder zwei =.
double Divide(double a, double b) Dividiert zwei double-Werte.
long Divide(long a, long b) Dividiert zwei long-Werte.
bool DoesTaskHostExist(string runtime, string architecture) Gibt zurück, ob derzeit ein Aufgabenhost für die angegebenen Laufzeit- und Architekturwerte installiert ist. Siehe MSBuild DoesTaskHostExist.
string Escape(string unescaped) Setzt gemäß den MSBuild-Escape-Regeln ein Escapezeichen vor die Zeichenfolge.
string EnsureTrailingSlash(string path) Wenn der angegebene Pfad keinen abschließenden Schrägstrich hat, fügen Sie einen hinzu. Wenn der Pfad eine leere Zeichenfolge ist, wird sie nicht geändert. Siehe MSBuild EnsureTrailingSlash.
string FilterTargetFrameworks(string incoming, string filter) Gibt die Liste der Zielframeworks zurück, die dem angegebenen Filter entsprechen. Ein Zielframework aus incoming wird beibehalten, wenn es mit einem der gewünschten Zielframeworks auf filter. Siehe MSBuild TargetFramework- und TargetPlatform-Funktionen.
string GetCurrentToolsDirectory() Abrufen des aktuellen MSBuild-Toolsverzeichnisses.
string GetMSBuildExtensionsPath() Ruft den Pfad der MSBuild-Erweiterungen ab. Wenn MSBuild.exeausgeführt wird, ist dies in der Regel der ausführbare MSBuild-Ordner. Wenn Visual Studio läuft, ist dies der MSBuild-Unterordner im Installationsverzeichnis von Visual Studio.
string GetMSBuildSDKsPath() Ruft das Verzeichnis ab, in dem SDKs für die aktuelle MSBuild-Instanz erwartet werden.
string GetProgramFiles32() Ruft den Stammordner des Dateisystems ab, in dem 32-Bit-Softwarepakete normalerweise installiert werden. Beispiel: C:\Program Files (x86).
string GetTargetFrameworkIdentifier(string targetFramework) Analysieren Sie den TargetFrameworkIdentifier aus dem TargetFramework. Siehe MSBuild TargetFramework- und TargetPlatform-Funktionen.
string GetTargetFrameworkVersion(string targetFramework, int versionPartCount) Analysiert TargetFrameworkVersion aus TargetFramework Siehe MSBuild TargetFramework- und TargetPlatform-Funktionen.
string GetTargetPlatformIdentifier(string targetFramework) Analysieren Sie den TargetPlatformIdentifier aus dem TargetFramework. Siehe MSBuild TargetFramework- und TargetPlatform-Funktionen.
string GetTargetPlatformVersion(string targetFramework, int versionPartCount) Analysiert TargetPlatformVersion aus TargetFramework Siehe MSBuild TargetFramework- und TargetPlatform-Funktionen.
string GetToolsDirectory32() Ruft das Verzeichnis ab, in dem sich 32-Bit-Versionen der MSBuild-Tools befinden.
string GetToolsDirectory64() Ruft das Verzeichnis ab, in dem sich 64-Bit-Versionen der MSBuild-Tools befinden.
string GetDirectoryNameOfFileAbove(string startingDirectory, string fileName) Suchen und zurückgeben Sie das Verzeichnis einer Datei entweder im angegebenen Verzeichnis oder an einem Speicherort in der Verzeichnisstruktur oberhalb dieses Verzeichnisses. Siehe MSBuild GetDirectoryNameOfFileAbove.
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. Siehe MSBuild GetPathOfFileAbove.
object GetRegistryValue(string keyName, string valueName, object defaultValue) Ermittelt den Wert des Registrierungsschlüssels und den Wert. Siehe MSBuild GetRegistryValue.
object GetRegistryValueFromView(string keyName, string valueName, object defaultValue, params object[] views) Ruft die Systemregistrierungsdaten mit dem Registrierungsschlüssel, dem Wert und einer oder mehreren geordneten Registrierungsansichten ab. Siehe MSBuild GetRegistryValueFromView.
string GetVsInstallRoot() Ruft den vollständigen Pfad zum Stamm des Visual Studio-Installationsordners ab, der der aktuellen Instanz von MSBuild zugeordnet ist.
bool IsOsPlatform(string platformString) Geben Sie an, ob die aktuelle Betriebssystemplattform ist platformString. platformString muss ein Mitglied von OSPlatform sein.
bool IsOsBsdLike() True, wenn das aktuelle Betriebssystem ein Unix-System im BSD-Stil ist.
bool IsOSUnixLike() True, wenn das aktuelle Betriebssystem ein Unix-System ist.
bool 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 ist, andernfalls "false". Siehe MSBuild TargetFramework- und TargetPlatform-Funktionen.
int LeftShift(int operand, int count) Verschiebung nach links um count bits. MSBuild 17.7 und höher.
string MakeRelative(string basePath, string path) Macht path relativ zu basePath. basePath muss ein absolutes Verzeichnis sein. Wenn nicht relativ gemacht werden kann, wird sie verbatim zurückgegeben.If path can't be made relative, it is returned verbatim. Vergleichbar zu Uri.MakeRelativeUri. Siehe MSBuild MakeRelative.
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.
double Multiply(double a, double b) Multipliziert zwei double-Werte.
long Multiply(long a, long b) Multipliziert zwei long-Werte.
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 NormalizePath(params string[] path) Ruft den kanonisierten vollständigen Pfad des bereitgestellten Pfads ab und stellt sicher, dass er die richtigen Verzeichnistrennzeichen für das aktuelle Betriebssystem enthält.
int RightShift(int operand, int count) Verschiebung nach rechts um count Bits, als vorzeichenbehaftete Ganzzahl. MSBuild 17.7 und höher.
int RightShiftUnsigned(int operand, int count) Verschiebung nach rechts um count Bits, wobei der Operand als Ganzzahl ohne Vorzeichen behandelt wird. MSBuild 17.7 und höher.
object StableStringHash(string toHash, StringHashingAlgorithm algo) Akzeptiert ein Zeichenfolgenargument und gibt einen Hashcode zurück, der garantiert stabil ist. Siehe MSBuild StableStringHash.
string SubstringByAsciiChars(string input, int start, int length) Gibt eine Teilzeichenfolge von input zurück, beginnend an der angegebenen start-Position und mit der angegebenen length, wobei die Zeichenfolge als ASCII-codiert behandelt wird.
double Subtract(double a, double b) Subtrahiert zwei double-Werte.
long Subtract(long a, long b) Subtrahiert zwei long-Werte.
string Unescape(string escaped) Entfernt gemäß den MSBuild-Escape-Regeln ein Escapezeichen vor der Zeichenfolge.
string ValueOrDefault(string conditionValue, string defaultValue) Gibt die Zeichenfolge im Parameter defaultValue nur zurück, wenn der Parameter conditionValue leer ist, andernfalls den Wert conditionValuezurückgeben. Siehe MSBuild ValueOrDefault.
bool VersionEquals(string a, string b) Gibt true zurück, wenn die Versionen a und b nach den folgenden Regeln gleichwertig sind. Siehe MSBuild-Versionsvergleichsfunktionen.
bool VersionGreaterThan(string a, string b) Gibt zurück true , wenn die Version a größer als b gemäß den folgenden Regeln ist. Siehe MSBuild-Versionsvergleichsfunktionen.
bool VersionGreaterThanOrEquals(string a, string b) Gibt true zurück, wenn die Version a gemäß den unten stehenden Regeln größer oder gleich b ist. Siehe MSBuild-Versionsvergleichsfunktionen.
bool VersionLessThan(string a, string b) Gibt zurück true , wenn die Version a kleiner als b gemäß den folgenden Regeln ist. Siehe MSBuild-Versionsvergleichsfunktionen.
bool VersionLessThanOrEquals(string a, string b) Geben Sie true zurück, wenn die Version a kleiner oder gleich b ist, gemäß den folgenden Regeln. Siehe MSBuild-Versionsvergleichsfunktionen.
bool VersionNotEquals(string a, string b) Gibt false zurück, wenn die Versionen a und b nach den folgenden Regeln gleichwertig sind. Siehe MSBuild-Versionsvergleichsfunktionen.

Geschachtelte Eigenschaftenfunktionen

Sie können Eigenschaftenfunktionen kombinieren, um komplexere Funktionen zu bilden, wie im folgenden Beispiel gezeigt:

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

In diesem Beispiel wird der Wert der FileAttributes zurückgegeben. Archive Bit (32 oder 0) der Datei, die vom Pfad tempFileangegeben wird. Beachten Sie, dass aufgezählte Datenwerte in einigen Kontexten nicht nach Namen 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, da ein numerischer Wert nicht konvertiert werden kann, wie diese Methode erwartet.

<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 Eigenschaftsfunktion in MSBuild gibt zurück, ob derzeit ein Aufgabenhost für die angegebenen Laufzeit- und Architekturwerte installiert ist.

Diese Eigenschaftsfunktion weist die folgende Syntax auf:

$([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 Eigenschaftsfunktion weist die folgende Syntax auf:

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

MSBuild GetDirectoryNameOfFileAbove

Die MSBuild-Eigenschaftsfunktion GetDirectoryNameOfFileAbove sucht nach oben nach einem Verzeichnis, das die angegebene Datei enthält, beginnend in (und einschließlich) des angegebenen Verzeichnisses. Er gibt den vollständigen Pfad des nächstgelegenen Verzeichnisses zurück, das die Datei enthält, wenn sie gefunden wird, andernfalls eine leere Zeichenfolge.

Diese Eigenschaftsfunktion weist die folgende Syntax auf:

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

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

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

Dieses Beispiel kann präziser geschrieben werden, indem stattdessen die GetPathOfFileAbove Funktion verwendet wird:

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

MSBuild GetPathOfFileAbove

Die MSBuild-Eigenschaftsfunktion GetPathOfFileAbove sucht nach oben nach einem Verzeichnis, das die angegebene Datei enthält, beginnend in (und einschließlich) des angegebenen Verzeichnisses. Er gibt den vollständigen Pfad der nächstgelegenen übereinstimmenden Datei zurück, wenn sie gefunden wird, andernfalls eine leere Zeichenfolge.

Diese Eigenschaftsfunktion weist die folgende Syntax auf:

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

dabei file handelt es sich um den Namen der zu suchenden Datei und startingDirectory ist ein optionales Verzeichnis, in dem die Suche gestartet werden soll. Standardmäßig beginnt die Suche im eigenen Verzeichnis der aktuellen Datei.

In diesem Beispiel wird gezeigt, wie Sie eine Datei namens dir.props in oder oberhalb des aktuellen Verzeichnisses importieren, nur 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))' != '' " />

Manchmal müssen Sie jedoch die Suche im übergeordneten Verzeichnis starten, um das Abgleichen der aktuellen Datei zu vermeiden. Dieses Beispiel zeigt, wie eine Datei "Directory.Build.props " die nächste Datei "Directory.Build.props" in einer streng höheren Ebene der Struktur importieren kann, ohne sich rekursiv selbst 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 MSBuild-Eigenschaftsfunktion GetRegistryValue gibt den Wert eines Registrierungsschlüssels zurück. Diese Funktion verwendet zwei Argumente, 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.

Die folgenden Beispiele zeigen, 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-Funktion GetRegistryValueFromView

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

Die Syntax für diese Eigenschaftsfunktion lautet:

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

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

Standardmäßig greift eine 32-Bit-Anwendung, die auf WOW64 ausgeführt wird, 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 32-Bit-Anwendungsregistrierungsansicht.
RegistryView.Registry64 Die 64-Bit-Anwendungsregistrierungsansicht.
RegistryView.Default Die Registrierungsansicht, die dem Prozess entspricht, auf dem die Anwendung ausgeführt wird.

Im Folgenden finden Sie ein Beispiel.

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

Der vorangehende Code ruft die SLRuntimeInstallPath-Daten des ReferenceAssemblies-Schlüssels ab, 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 MSBuild-Eigenschaftsfunktion MakeRelative gibt den relativen Pfad des zweiten Pfads relativ zum ersten Pfad zurück. Jeder Pfad kann eine Datei oder ein Ordner sein.

Diese Eigenschaftsfunktion weist die folgende Syntax auf:

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

Der folgende Code ist ein Beispiel für diese Syntax.

<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-Eigenschaftsfunktion StableStringHash akzeptiert ein Zeichenfolgenargument und gibt einen Hashcode zurück, der garantiert stabil ist, was bedeutet, dass derselbe Code immer für dieselbe Zeichenfolgeneingabe 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 GetHashCodeauf plattformübergreifender Architektur stabil. Es ist nicht garantiert, dass es in verschiedenen MSBuild-Versionen stabil ist.

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

Das folgende Beispiel zeigt, wie diese Funktion verwendet wird.

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

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

Mit MSBuild, Version 17.10 und höher, akzeptiert diese Funktion das zweite, optionale Argument, das den zu verwendenden Hashingalgorithmus 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 das Aufrufen der Funktion ohne das zweite Argument bei. Gibt signierte 32-Bit-Ganzzahl mit ähnlichen Eigenschaften wie string.GetHashCode.
  • Fnv1a32bit – Gibt signierte 32-Bit-Ganzzahl zurück, die einen Fowler-Noll-Vo-Hash der Version "1a" der angegebenen Zeichenfolge darstellt.
  • Fnv1a64bit – Gibt signierte 64-Bit-Ganzzahl zurück, die einen Fowler-Noll-Vo-Hash der Version "1a" der angegebenen Zeichenfolge darstellt.
  • Sha256 – Gibt eine ungekennzeichnete Hexzeichenfolge zurück, die einen SHA256-Hash der angegebenen Zeichenfolge darstellt.

MSBuild ValueOrDefault

Die MSBuild-Eigenschaftsfunktion ValueOrDefault gibt das erste Argument zurück, es sei denn, sie ist null oder leer. Wenn das erste Argument null oder leer ist, gibt die Funktion das zweite Argument zurück.

Das folgende Beispiel zeigt, wie diese Funktion verwendet wird.

<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- und TargetPlatform-Funktionen

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

Funktionssignatur BESCHREIBUNG
FilterTargetFrameworks(string incoming, string filter) Gibt die Liste der Zielframeworks zurück, die dem angegebenen Filter entsprechen. Ein Zielframework aus incoming wird beibehalten, wenn es mit einem der gewünschten Zielframeworks auf filter.
GetTargetFrameworkIdentifier(string targetFramework) Analysieren Sie den TargetFrameworkIdentifier aus dem TargetFramework.
GetTargetFrameworkVersion(string targetFramework, int versionPartCount) Analysiert TargetFrameworkVersion aus TargetFramework
GetTargetPlatformIdentifier(string targetFramework) Analysieren Sie den TargetPlatformIdentifier aus dem 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 ist, andernfalls "false".

Der versionPartCount Parameter von GetTargetFrameworkVersion und GetTargetPlatformVersion weist den Standardwert 2 auf.

Das folgende Beispiel zeigt, wie diese Funktionen verwendet werden.

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

Mit MSBuild 17.6 und höher (oder .NET 7 und höher) können Sie diese Eigenschaftsfunktion verwenden, um eine Teilmenge einer Liste von Target Framework Monikers (TFMs) auszuwählen, um die Liste auf diese Frameworks zu beschränken, die der Liste der TFMs entsprechen, die dem Filterargument entsprechen.

Beispielsweise, wenn incomingnet6.0;net7.0;netstandard2.0 ist und filternet7.0;netstandard2.0 ist, lautet das Ergebnis net7.0;netstandard2.0.

MSBuild-Versionsvergleichsfunktionen

MSBuild 16.5 und höher definieren mehrere Funktionen zum Vergleichen von Zeichenfolgen, die Versionen darstellen.

Hinweis

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

Funktionssignatur BESCHREIBUNG
VersionEquals(string a, string b) Gibt true zurück, wenn die Versionen a und b nach den folgenden Regeln gleichwertig sind.
VersionGreaterThan(string a, string b) Gibt zurück true , wenn die Version a größer als b gemäß den folgenden Regeln ist.
VersionGreaterThanOrEquals(string a, string b) Gibt true zurück, wenn die Version a gemäß den unten stehenden Regeln größer oder gleich b ist.
VersionLessThan(string a, string b) Gibt zurück true , wenn die Version a kleiner als b gemäß den folgenden Regeln ist.
VersionLessThanOrEquals(string a, string b) Geben Sie true zurück, wenn die Version a kleiner oder gleich b ist, gemäß den folgenden Regeln.
VersionNotEquals(string a, string b) Gibt false zurück, wenn die Versionen a und b nach den folgenden Regeln gleichwertig sind.

In diesen Methoden werden Versionen wie System.Version analysiert, mit den folgenden Ausnahmen:

  • Führende v oder V werden ignoriert, was den Vergleich mit $(TargetFrameworkVersion) ermöglicht.

  • Alles vom ersten '-' oder '+' bis zum Ende der Versionszeichenfolge wird ignoriert. Dies ermöglicht die Übergabe semantischer Versionen (Semver), obwohl die Reihenfolge nicht mit Semver identisch ist. Stattdessen weisen Präreleasebezeichner und Buildmetadaten keine Sortiergewichtung auf. Dies kann z. B. hilfreich sein, um ein Feature für >= x.y zu aktivieren und es bei x.y.z-pre in Kraft treten zu lassen.

  • Nicht angegebene Teile sind identisch mit Nullwertteilen. (x == x.0 == x.0.0 == x.0.0.0).

  • Leerzeichen sind in ganzzahligen Komponenten nicht zulässig.

  • Die Hauptversion ist nur gültig (3 ist gleich 3.0.0.0)

  • + ist nicht als positives Zeichen in ganzzahligen Komponenten zulässig (sie wird als Semver-Metadaten behandelt und ignoriert)

Tipp

Vergleiche von TargetFramework-Eigenschaften sollten in der Regel IsTargetFrameworkCompatible verwenden, anstatt Versionen zu extrahieren und zu vergleichen. Dies ermöglicht den Vergleich von TargetFrameworks, die sowohl in TargetFrameworkIdentifier als auch in der Version variieren.

MSBuild-Bedingungsfunktionen

Die Funktionen Exists und HasTrailingSlash sind keine Eigenschaftsfunktionen. Sie sind für die Verwendung mit dem Condition Attribut verfügbar. Siehe MSBuild-Bedingungen.

Verwandte Inhalte

  • Last updated on