Funzioni delle proprietà

Le funzioni di proprietà sono chiamate a metodi .NET visualizzati nelle definizioni delle proprietà di MSBuild. A differenza delle attività, le funzioni di proprietà possono essere usate all'esterno delle destinazioni. Le funzioni di proprietà vengono valutate ogni volta che vengono espanse le proprietà o gli elementi. Pertanto, per le proprietà e gli elementi esterni a qualsiasi destinazione, le funzioni di proprietà vengono valutate prima di qualsiasi esecuzione di destinazione. Per i gruppi di proprietà e i gruppi di elementi all'interno delle destinazioni, le funzioni di proprietà vengono valutate quando viene valutata la destinazione.

Senza usare le attività MSBuild, è possibile leggere l'ora di sistema, confrontare stringhe, trovare la corrispondenza per espressioni regolari ed eseguire altre azioni nello script di compilazione. MSBuild tenterà di convertire le stringhe in numeri e i numeri in stringhe nonché di eseguire altre conversioni secondo le esigenze.

Nei valori stringa restituiti da funzioni di proprietà i caratteri speciali sono sottoposti a escape. Se si vuole che il valore venga trattato come se fosse stato inserito direttamente nel file di progetto, usare $([MSBuild]::Unescape()) per rimuovere gli escape dai caratteri speciali.

Sintassi delle funzioni di proprietà

Di seguito sono elencati tre tipi di funzioni di proprietà. Ogni funzione presenta una sintassi diversa:

• Funzioni di proprietà stringa (istanza)
• Funzioni di proprietà statiche
• Funzioni di proprietà MSBuild

Funzioni di proprietà stringa

Tutti i valori delle proprietà di compilazione sono soltanto valori stringa. Per agire su qualsiasi valore di proprietà è possibile usare i metodi stringa (istanza). Ad esempio, è possibile estrarre il nome di unità, ovvero i primi tre caratteri, da una proprietà di compilazione che rappresenta un percorso completo con questo codice:

$(ProjectOutputFolder.Substring(0,3))

Funzioni di proprietà statiche

Nello script di compilazione è possibile accedere alle proprietà e ai metodi statici di molte classi di sistema. Per ottenere il valore di una proprietà statica, utilizzare la sintassi seguente, dove Class è il nome della classe di sistema e Property è il nome della proprietà.

$([Class]::Property)

Ad esempio, è possibile usare il codice seguente per impostare una proprietà di compilazione sulla data e sull'ora correnti.

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

Per chiamare un metodo statico, utilizzare la sintassi seguente, dove Class è il nome della classe di sistema, Method è il nome del metodo ed (Parameters) è l'elenco di parametri per il metodo :

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

Ad esempio per impostare una proprietà di compilazione su un nuovo GUID, è possibile usare lo script seguente:

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

Nelle funzioni di proprietà statiche è possibile usare qualsiasi metodo o proprietà statica pubblica definita in .NET Standard 2.0 per queste classi di sistema:

• System.Byte
• System.Char
• System.Convert
• System.DateTime
• System.DateTimeOffset (disponibile in MSBuild 17.3 e versioni successive)
• 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
• Timespan
• System.Text.RegularExpressions.Regex
• System.UriBuilder
• System.Version
• Microsoft.Build.Utilities.ToolLocationHelper

Inoltre, è possibile usare le proprietà e i metodi statici seguenti:

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

Chiamata di metodi di istanza su proprietà statiche

Se si accede a una proprietà statica che restituisce un'istanza di un oggetto, è possibile richiamare i metodi di istanza di tale oggetto. Per richiamare un metodo di istanza, utilizzare la sintassi seguente, dove Class è il nome della classe di sistema, è il nome della proprietà, Property Method è il nome del metodo ed (Parameters) è l'elenco di parametri per il metodo :

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

Il nome della classe deve essere completo con lo spazio dei nomi.

Ad esempio, è possibile usare il codice seguente per impostare una proprietà di compilazione sulla data corrente.

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

Funzioni di proprietà MSBuild

È possibile accedere a diversi metodi statici nella compilazione per supportare funzionalità aritmetiche, operazioni logiche bit per bit nonché la gestione dei caratteri di escape. È possibile accedere a questi metodi usando la sintassi seguente, dove Method è il nome del metodo ed (Parameters) è l'elenco di parametri per il metodo .

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

Ad esempio, per sommare due proprietà che presentano valori numerici, usare il codice seguente.

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

Di seguito è riportato un elenco di funzioni di proprietà MSBuild:

Funzioni di proprietà annidate

È possibile combinare funzioni di proprietà per formare funzioni più complesse, come illustrato nell'esempio seguente:

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

In questo esempio viene restituito il valore di FileAttributes.Archive bit (32 o 0) del file specificato dal percorso tempFile. Si noti che i valori dei dati enumerati non possono essere visualizzati in base al nome in alcuni contesti. Nell'esempio precedente è necessario usare invece il valore numerico (32). In altri casi, a seconda delle aspettative del metodo chiamato, è necessario usare il valore dei dati enumerazione. Nell'esempio seguente il valore RegexOptionsdi enumerazione .ECMAScript deve essere utilizzato perché non è possibile convertire un valore numerico come previsto da questo metodo.

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

Nelle funzioni di proprietà annidate è possibile specificare anche i metadati. Per altre informazioni, vedere Batch.

MSBuild DoesTaskHostExist

La funzione di proprietà DoesTaskHostExist in MSBuild restituisce un valore che indica se un host attività è attualmente installato per i valori di architettura e runtime specificati.

Questa funzione di proprietà presenta la seguente sintassi:

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

EnsureTrailingSlash di MSBuild

La funzione di proprietà EnsureTrailingSlash in MSBuild aggiunge una barra finale se non ne esiste già una.

Questa funzione di proprietà presenta la seguente sintassi:

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

MSBuild GetDirectoryNameOfFileAbove

La funzione della proprietà MSBuild GetDirectoryNameOfFileAbove cerca verso l'alto una directory contenente il file specificato, a partire da (e includendo) la directory specificata. Restituisce il percorso completo della directory più vicina contenente il file se viene trovato, altrimenti una stringa vuota.

Questa funzione di proprietà presenta la seguente sintassi:

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

In questo esempio viene illustrato come importare il file EnlistmentInfo.props più vicino nella cartella corrente, solo se viene trovata una corrispondenza:

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

Si noti che questo esempio può essere scritto in modo più conciso usando invece la GetPathOfFileAbove funzione :

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

GetPathOfFileAbove di MSBuild

La funzione della proprietà MSBuild GetPathOfFileAbove cerca verso l'alto una directory contenente il file specificato, a partire da (e includendo) la directory specificata. Restituisce il percorso completo del file corrispondente più vicino, se trovato, altrimenti una stringa vuota.

Questa funzione di proprietà presenta la seguente sintassi:

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

dove file è il nome del file da cercare ed startingDirectory è una directory facoltativa in cui avviare la ricerca. Per impostazione predefinita, la ricerca verrà avviata nella directory del file corrente.

In questo esempio viene illustrato come importare un file denominato dir.props in o sopra la directory corrente, solo se viene trovata una corrispondenza:

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

equivalente funzionalmente a

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

Tuttavia, a volte è necessario avviare la ricerca nella directory padre, per evitare la corrispondenza con il file corrente. In questo esempio viene illustrato come un file Directory.Build.props possa importare il file Directory.Build.props più vicino in un livello rigorosamente superiore dell'albero, senza importare in modo ricorsivo se stesso:

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

equivalente funzionalmente a

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

MSBuild GetRegistryValue

La funzione di proprietà MSBuild GetRegistryValue restituisce il valore di una chiave del Registro di sistema. Questa funzione accetta due argomenti, il nome della chiave e il nome del valore e restituisce il valore dal Registro di sistema. Se non si specifica un nome del valore, viene restituito il valore predefinito.

Gli esempi seguenti mostrano come viene usata questa funzione:

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

La funzione di proprietà MSBuild GetRegistryValueFromView ottiene i dati del Registro di sistema in base alla chiave e al valore del Registro di sistema forniti, nonché a una o più visualizzazioni ordinate del Registro di sistema. La chiave e il valore vengono cercati in ogni visualizzazione del Registro di sistema in ordine, finché non vengono trovati.

Di seguito è indicata la sintassi per la funzione della proprietà:

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

Il sistema operativo Windows a 64 bit gestisce una chiave del Registro di sistema HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node che presenta una visualizzazione del Registro di sistema HKEY_LOCAL_MACHINE\SOFTWARE per le applicazioni a 32 bit.

Per impostazione predefinita, un'applicazione a 32 bit in esecuzione su WOW64 accede alla visualizzazione del Registro di sistema a 32 bit e un'applicazione a 64 bit accede alla visualizzazione del Registro di sistema a 64 bit.

Sono disponibili le visualizzazioni del Registro di sistema seguenti:

Di seguito viene riportato un esempio.

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

Ottiene i dati SLRuntimeInstallPath della chiave ReferenceAssemblies, cercandoli in primo luogo nella visualizzazione del Registro di sistema a 64 bit, quindi in quella a 32 bit.

MSBuild MakeRelative

La funzione di proprietà MSBuild MakeRelative restituisce il percorso relativo del secondo percorso relativo al primo percorso. Ogni percorso può essere un file o una cartella.

Questa funzione di proprietà presenta la seguente sintassi:

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

Il codice seguente è un esempio di questa sintassi.

<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

La funzione della proprietà MSBuild StableStringHash accetta un argomento stringa e restituisce un codice hash che è garantito essere stabile, ovvero lo stesso codice viene sempre restituito per lo stesso input di stringa. L'hash restituito è lo stesso indipendentemente dal fatto che MSBuild o dotnet build sia usato ed è stabile nell'architettura della piattaforma, a differenza del metodo GetHashCode.NET . Non è garantito che sia stabile in diverse versioni di MSBuild.

Questa funzione è disponibile in MSBuild 16.9.0 o versione successiva.

Gli esempi seguenti mostrano come viene usata questa funzione.

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

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

Da MSBuild versione 17.10.0 questa funzione accetta secondo argomento facoltativo che richiede l'algoritmo hash da usare:

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

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

Il secondo argomento non fa distinzione tra maiuscole e minuscole e supporta attualmente i valori seguenti:

• Legacy: mantiene lo stesso comportamento della chiamata alla funzione senza il secondo argomento. Restituisce un intero con segno a 32 bit con proprietà simili a string.GetHashCode.
• Fnv1a32bit: restituisce un intero con segno a 32 bit che rappresenta un hash Fowler–Noll-Vo della versione '1a' della stringa specificata.
• Fnv1a64bit: restituisce un intero con segno a 64 bit che rappresenta un hash Fowler–Noll-Vo della versione '1a' della stringa specificata.
• Sha256: restituisce una stringa esadecimale senza prefisso che rappresenta un hash SHA256 della stringa specificata.

MSBuild ValueOrDefault

La funzione di proprietà MSBuild ValueOrDefault restituisce il primo argomento, a meno che non sia null o vuoto. Se il primo argomento è null o vuoto, la funzione restituisce il secondo argomento.

Gli esempi seguenti mostrano come viene usata questa funzione.

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

Funzioni TargetFramework e TargetPlatform di MSBuild

MSBuild 16.7 e versioni successive definiscono diverse funzioni per la gestione delle proprietà TargetFramework e TargetPlatform.

Il versionPartCount parametro di GetTargetFrameworkVersion e GetTargetPlatformVersion ha un valore predefinito pari a 2.

Nell'esempio seguente viene illustrato come vengono usate queste funzioni.

<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

Funzioni di confronto delle versioni di MSBuild

MSBuild 16.5 e versioni successive definiscono diverse funzioni per confrontare le stringhe che rappresentano le versioni.

In questi metodi, le versioni vengono analizzate come System.Version, con le eccezioni seguenti:

• L'inizialità v o V viene ignorata, che consente il confronto con $(TargetFrameworkVersion).

• Tutti gli elementi dal primo '-' o '+' alla fine della stringa di versione vengono ignorati. Ciò consente il passaggio di versioni semantiche (semver), anche se l'ordine non è uguale a semver. Gli identificatori di versione preliminare e i metadati di compilazione non hanno invece alcun peso di ordinamento. Questo può essere utile, ad esempio, per attivare una funzionalità per >= x.y e far sì che venga attivato su x.y.z-pre.

• Le parti non specificate sono uguali a zero parti di valore. (x == x.0 == x.0.0 == x.0.0.0).

• Gli spazi vuoti non sono consentiti nei componenti integer.

• Solo la versione principale è valida (3 è uguale a 3.0.0.0)

• + non è consentito come componenti integer di accesso positivo (viene considerato come metadati semver e ignorato)

Funzioni di condizione DI MSBuild

Le funzioni Exists e HasTrailingSlash non sono funzioni di proprietà. Sono disponibili per l'uso con l'attributo Condition . Vedere Condizioni di MSBuild.

Contenuto correlato

• Proprietà di MSBuild

• Panoramica di MSBuild