proprietà di MSBuild

  • Articolo

Le proprietà sono coppie nome-valore che possono essere usate per configurare le compilazioni. Le proprietà sono utili per passare i valori alle attività, valutare le condizioni e archiviare i valori a cui si farà riferimento nel file di progetto.

Definire e fare riferimento alle proprietà in un file di progetto

Per dichiarare le proprietà, è necessario creare un elemento con lo stesso nome della proprietà, come figlio di un elemento PropertyGroup. l codice XML seguente, ad esempio, crea una proprietà denominata BuildDir con un valore Build.

<PropertyGroup>
    <BuildDir>Build</BuildDir>
</PropertyGroup>

I nomi di proprietà validi iniziano con una lettera maiuscola o minuscola o un carattere di sottolineatura (_); i caratteri successivi validi includono caratteri alfanumerici (lettere o cifre), carattere di sottolineatura e trattino (-).

In tutto il file di progetto, le proprietà vengono a cui viene fatto riferimento usando la sintassi $(<PropertyName>). Ad esempio, la proprietà nell'esempio precedente viene fatto riferimento tramite $(BuildDir).

I valori delle proprietà possono essere modificati ridefinendo la proprietà. È possibile assegnare un nuovo valore alla proprietà BuildDir usando questo codice XML:

<PropertyGroup>
    <BuildDir>Alternate</BuildDir>
</PropertyGroup>

Le proprietà vengono valutate nell'ordine in cui sono visualizzate nel file di progetto. Il nuovo valore per BuildDir deve essere dichiarato dopo che è stato assegnato il valore precedente.

Proprietà riservate

In MSBuild alcuni nomi di proprietà sono riservati per archiviare le informazioni relative al file di progetto e ai file binari di MSBuild. Per fare riferimento a queste proprietà, si usa la notazione $, come per qualsiasi altra proprietà. Ad esempio, $(MSBuildProjectFile) restituisce il nome file completo del file di progetto, inclusa l'estensione di file.

Per altre informazioni, vedere Procedura: Fare riferimento al nome o al percorso del file di progetto e Proprietà riservate e note MSBuild.

Proprietà interne di MSBuild

Le proprietà definite nei file di importazione standard che iniziano con un carattere di sottolineatura (_) sono private per MSBuild e non devono essere lette, reimpostate o sottoposte a override nel codice utente.

Proprietà dell'ambiente

È possibile fare riferimento alle variabili di ambiente nei file di progetto esattamente come si fa riferimento alle proprietà riservate. Ad esempio, per usare la variabile di ambiente PATH nel file di progetto, usare $(Path). Se il progetto contiene una definizione di una proprietà con lo stesso nome di una proprietà di ambiente, la proprietà nel progetto esegue l'override del valore della variabile di ambiente.

A ogni progetto MSBuild è associato un blocco di ambiente isolato: nel relativo blocco personalizzato sono visualizzate solo le letture e le scritture. Tramite MSBuild vengono lette le variabili di ambiente solo durante l'inizializzazione della raccolta di proprietà, prima che il file di progetto venga valutato o compilato. Successivamente, le proprietà dell'ambiente sono statiche, cioè ciascuno strumento generato inizia con gli stessi nomi e valori.

Per ottenere il valore corrente delle variabili di ambiente dall'interno di uno strumento generato, usare le funzioni di proprietà System.Environment.GetEnvironmentVariable. Il metodo consigliato, tuttavia, consiste nell'utilizzare il parametro dell'attività EnvironmentVariables. Le proprietà dell'ambiente impostate in questa matrice di stringhe possono essere passate allo strumento generato senza influire sulle variabili di ambiente del sistema.

Suggerimento

Non tutte le variabili di ambiente vengono lette per diventare proprietà iniziali. Tutte le variabili di ambiente il cui nome non è un nome di proprietà MSBuild valido, ad esempio "386", vengono ignorate.

Per altre informazioni, vedere Procedura: Usare le variabili di ambiente in una compilazione.

Proprietà del Registro di sistema

È possibile leggere i valori del Registro di sistema usando la sintassi seguente, dove Hive è l'hive del Registro di sistema (ad esempio, HKEY_LOCAL_MACHINE), MyKey è il nome della chiave, MySubKey è il nome della sottochiave e Value è il valore della sottochiave.

$(registry:Hive\MyKey\MySubKey@Value)

Per ottenere il valore della sottochiave predefinito, omettere Value.

$(registry:Hive\MyKey\MySubKey)

Questo valore del Registro di sistema può essere usato per inizializzare una proprietà di compilazione. Ad esempio, per creare una proprietà di compilazione che rappresenta la home page del Web browser di Visual Studio, usare questo codice:

<PropertyGroup>
  <VisualStudioWebBrowserHomePage>
    $(registry:HKEY_CURRENT_USER\Software\Microsoft\VisualStudio\14.0\WebBrowser@HomePage)
  </VisualStudioWebBrowserHomePage>
<PropertyGroup>

Avviso

Nella versione .NET SDK di MSBuild (dotnet build), le proprietà del Registro di sistema non sono supportate.

Creare proprietà durante l'esecuzione

Alle proprietà non comprese in elementi Target vengono assegnati valori durante la fase di valutazione di una compilazione. Durante la fase di esecuzione successiva, le proprietà possono essere create o modificate come segue:

  • Una proprietà può essere creata da qualsiasi attività. Per creare una proprietà, l'elemento Task deve avere un elemento Output figlio con un attributo PropertyName.

  • Una proprietà può essere creata dall'attività CreateProperty. Questo utilizzo è deprecato.

  • Target gli elementi possono contenere PropertyGroup elementi che possono contenere dichiarazioni di proprietà.

Proprietà globali

MSBuild permette di impostare le proprietà nella riga di comando usando l'opzione -property (o -p). Questi valori delle proprietà globali eseguono l'override dei valori delle proprietà impostati nel file di progetto. incluse le proprietà di ambiente, ma non le proprietà riservate, che non possono essere modificate.

L'esempio seguente imposta la proprietà Configuration globale su DEBUG.

msbuild.exe MyProj.proj -p:Configuration=DEBUG

Le proprietà globali possono anche essere impostate o modificate per i progetti figlio in una compilazione a più progetti usando l'attributo Properties dell'attività di MSBuild. Le proprietà globali vengono anche inoltrate ai progetti figlio, a meno che l'attributo RemoveProperties dell'attività MSBuild non venga usato per specificare l'elenco di proprietà da non inoltrare. Per altre informazioni, vedere Attività MSBuild.

Proprietà locali

Le proprietà locali possono essere reimpostate in un progetto. Impossibile modificare le proprietà globali. Quando una proprietà locale viene impostata dalla riga di comando con l'opzione -p , l'impostazione nel file di progetto ha la precedenza sulla riga di comando.

Specificare una proprietà locale usando l'attributo TreatAsLocalProperty in un tag di progetto.

Il codice seguente specifica che due proprietà sono locali:

<Project Sdk="Microsoft.Net.Sdk" TreatAsLocalProperty="Prop1;Prop2">

Le proprietà locali non vengono inoltrate ai progetti figlio in una compilazione multiprogetto. Se si specifica un valore nella riga di comando con l'opzione -p , ai progetti figlio viene assegnato il valore della proprietà globale anziché il valore locale modificato nel progetto padre, ma il progetto figlio (o una delle relative importazioni) può anche modificarlo con il proprio TreatAsLocalProperty.

Esempio con proprietà locali

Nell'esempio di codice seguente viene illustrato l'effetto di TreatAsLocalProperty:

<!-- test1.proj -->
<Project TreatAsLocalProperty="TreatedAsLocalProp">
    <PropertyGroup>
        <TreatedAsLocalProp>LocalOverrideValue</TreatedAsLocalProp>
    </PropertyGroup>

    <Target Name="Go">
        <MSBuild Projects="$(MSBuildThisFileDirectory)\test2.proj" Targets="Go2" Properties="Inner=true" />
    </Target>

    <Target Name="Go2" BeforeTargets="Go">
        <Warning Text="TreatedAsLocalProp($(MSBuildThisFileName)): $(TreatedAsLocalProp)" />
    </Target>
</Project>

<!-- test2.proj -->
<Project TreatAsLocalProperty="TreatedAsLocalProp">
    <Target Name="Go2">
        <Warning Text="TreatedAsLocalProp($(MSBuildThisFileName)): $(TreatedAsLocalProp)" />
    </Target>
</Project>

Si supponga di compilare la riga di comando test1.proj e assegnare TreatedAsLocalProperty il valore GlobalOverrideValueglobale :

dotnet msbuild .\test1.proj -p:TreatedAsLocalProp=GlobalOverrideValue

L'output è il seguente:

test1.proj(11,9): warning : TreatedAsLocalProp(test): LocalOverrideValue
test2.proj(3,9): warning : TreatedAsLocalProp(test2): GlobalOverrideValue

Il progetto figlio eredita il valore globale, ma il progetto padre usa la proprietà impostata localmente.

Proprietà e importazioni locali

Quando TreatAsLocalProperty l'attributo viene usato nel progetto importato, l'ordine è importante quando si considera quale valore ottiene la proprietà.

L'esempio di codice seguente illustra l'effetto di TreatAsLocalProperty su un progetto importato:

<!-- importer.proj -->
<Project>
    <PropertyGroup>
        <TreatedAsLocalProp>FirstOverrideValue</TreatedAsLocalProp>
    </PropertyGroup>

    <Import Project="import.props" />

    <PropertyGroup>
        <TreatedAsLocalProp Condition=" '$(TrySecondOverride)' == 'true' ">SecondOverrideValue</TreatedAsLocalProp>
    </PropertyGroup>

    <Target Name="Go">
        <Warning Text="TreatedAsLocalProp($(MSBuildThisFileName)): $(TreatedAsLocalProp)" />
    </Target>
</Project>

<!-- import.proj -->
<Project TreatAsLocalProperty="TreatedAsLocalProp">
    <PropertyGroup>
        <TreatedAsLocalProp>ImportOverrideValue</TreatedAsLocalProp>
    </PropertyGroup>

    <!-- Here, TreatedAsLocalProp has the value "ImportOverrideValue"-->
</Project>

Si supponga di compilare importer.proj e impostare un valore globale per TreatedAsLocalProp come indicato di seguito:

dotnet msbuild .\importer.proj -p:TreatedAsLocalProp=GlobalOverrideValue

L'output è il seguente:

importer.proj(9,9): warning : TreatedAsLocalProp(importer.proj): GlobalOverrideValue

Si supponga ora di compilare con la proprietà TrySecondOverride in true:

dotnet msbuild .\importer.proj -p:TreatedAsLocalProp=GlobalOverrideValue -p:TrySecondOverride=true

L'output è il seguente:

importer.proj(13,9): warning : TreatedAsLocalProp(importer.proj): SecondOverrideValue

L'esempio mostra che la proprietà viene considerata locale dopo il progetto importato in cui è stato usato l'attributo TreatAsLocalProperty , non solo all'interno del file importato. Il valore della proprietà è interessato dal valore di override globale, ma solo prima del progetto importato in cui TreatAsLocalProperty viene utilizzato.

Per altre informazioni, vedere Elemento Project (MSBuild) e Procedura: Compilare gli stessi file di origine con opzioni diverse.

Funzioni delle proprietà

A partire da .NET Framework versione 4 è possibile utilizzare funzioni delle proprietà per valutare gli script MSBuild. È possibile leggere l'ora di sistema, confrontare stringhe, trovare la corrispondenza per espressioni regolari ed eseguire numerose altre azioni nello script di compilazione senza usare le attività di MSBuild.

È possibile usare metodi di stringa (istanza) per operare su qualsiasi valore della proprietà ed è possibile chiamare i metodi statici di diverse classi di sistema. È ad esempio possibile impostare una proprietà di compilazione sulla data odierna come segue.

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

Per altre informazioni e per un elenco di funzioni delle proprietà, vedere Funzioni delle proprietà.

Archiviare codice XML nelle proprietà

Le proprietà possono contenere codice XML arbitrario, che consente di passare i valori alle attività o di visualizzare le informazioni di registrazione. L'esempio seguente illustra la proprietà ConfigTemplate, che ha un valore contenente codice XML e riferimenti ad altre proprietà. MSBuild sostituisce i riferimenti alle proprietà usando i rispettivi valori di proprietà. I valori delle proprietà vengono assegnati nell'ordine in cui sono visualizzati. In questo esempio quindi $(MySupportedVersion), $(MyRequiredVersion) e $(MySafeMode) devono essere già stati definiti.

<PropertyGroup>
    <ConfigTemplate>
        <Configuration>
            <Startup>
                <SupportedRuntime
                    ImageVersion="$(MySupportedVersion)"
                    Version="$(MySupportedVersion)"/>
                <RequiredRuntime
                    ImageVersion="$(MyRequiredVersion)"
                    Version="$(MyRequiredVersion)"
                    SafeMode="$(MySafeMode)"/>
            </Startup>
        </Configuration>
    </ConfigTemplate>
</PropertyGroup>

Contenuto correlato