Proprietà di MSBuild

Articolo
06/10/2015

Le proprietà sono coppie nome-valore che è possibile utilizzare per configurare le compilazioni. Le proprietà sono utili per passare valori alle attività, valutare condizioni e archiviare valori a cui verrà fatto riferimento nel file di progetto.

Definizione e riferimento a proprietà in un file di progetto

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

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

Nel file di progetto viene fatto riferimento alle proprietà utilizzando la sintassi $(PropertyName). Per fare riferimento alla proprietà dell'esempio precedente si utilizza, ad esempio, $(BuildDir).

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

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

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

Proprietà riservate

MSBuild riserva alcuni nomi di proprietà per archiviare le informazioni relative al file di progetto e ai file binari di MSBuild. A queste proprietà viene fatto riferimento utilizzando la notazione $, come per qualsiasi altra proprietà. $(MSBuildProjectFile) restituisce, ad esempio, il nome file completo del file di progetto, inclusa l'estensione.

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

Proprietà di ambiente

È possibile fare riferimento alle variabili di ambiente nei file di progetto nello stesso modo utilizzato per le proprietà riservate. Per utilizzare, ad esempio, la variabile di ambiente PATH nel file di progetto, utilizzare $(Path). Se il progetto contiene una definizione di proprietà con lo stesso nome di una proprietà di ambiente, tale proprietà nel progetto esegue l'override del valore della variabile di ambiente.

Ogni progetto MSBuild dispone di un blocco di ambiente isolato: vede, legge e scrive solo il proprio blocco. MSBuild legge le variabili di ambiente solo durante l'inizializzazione della raccolta di proprietà, prima che il file di progetto venga analizzato e compilato. Successivamente le proprietà dell'ambiente sono statiche, ovvero 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, utilizzare Funzioni delle proprietà System.Environment.GetEnvironmentVariable. Il metodo consigliato, tuttavia, è quello di utilizzare il parametro dell'attività EnvironmentVariables. Le proprietà dell'ambiente impostate in questo array di stringhe possono essere passate allo strumento generato senza influenzare le variabili di ambiente del sistema.

Suggerimento

Non tutte le variabili di ambiente saranno lette e diventeranno proprietà iniziali.Qualsiasi variabile di ambiente il cui nome non è un nome valido delle proprietà di MSBuild (ad esempio "386") viene ignorata.

Per ulteriori informazioni, vedere Procedura: utilizzare le variabili di ambiente in una compilazione.

Proprietà del Registro di sistema

È possibile leggere i valori del Registro di sistema utilizzando la sintassi seguente, dove Hive è l'hive del Registro di sistema, ad esempio HKEY_LOCAL_MACHINE, Key è il nome della chiave, SubKey è il nome della sottochiave e Value è il valore della sottochiave.

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

Per ottenere il valore predefinito della sottochiave, omettere Value.

$(registry:Hive\MyKey\MySubKey)

Questo valore del Registro di sistema può essere utilizzato per inizializzare una proprietà di compilazione. Per creare, ad esempio, una proprietà di compilazione che rappresenta la home page del Web browser di Visual Studio, utilizzare il codice seguente:

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

Proprietà globali

MSBuild consente di impostare le proprietà nella riga di comando utilizzando l'opzione /property (o /p). Questi valori delle proprietà globali eseguono l'override dei valori delle proprietà impostati nel file di progetto. Questo vale anche per le proprietà di ambiente, ma non per le proprietà riservate, che non possono essere modificate.

Nell'esempio seguente la proprietà globale Configuration viene impostata 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 di più progetti utilizzando l'attributo Properties dell'attività MSBuild. Per ulteriori informazioni, vedere Attività MSBuild.

Se si specifica una proprietà utilizzando l'attributo TreatAsLocalProperty in un tag di progetto, il valore di quella proprietà globale non sovrascrive il valore della proprietà impostato nel file di progetto. Per ulteriori informazioni, vedere Elemento Project (MSBuild) e Procedura: compilare gli stessi file di origine con opzioni diverse.

Funzioni delle proprietà

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 molte altre azioni negli script di compilazione senza utilizzare le attività MSBuild.

È possibile utilizzare metodi di stringa (istanza) per eseguire operazioni su qualsiasi valore delle proprietà ed è possibile chiamare i metodi statici di numerose classi di sistema. È ad esempio possibile impostare una proprietà di compilazione sulla data corrente procedendo come indicato di seguito:

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

Per un elenco delle funzioni delle proprietà disponibili e per informazioni sul relativo utilizzo, vedere Funzioni delle proprietà.

Creazione di proprietà durante l'esecuzione

Alle proprietà al di fuori degli 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 indicato di seguito:

Una proprietà può essere creata da qualsiasi attività. Per creare una proprietà, l'elemento Task deve disporre di un elemento Output figlio con un attributo PropertyName.
Una proprietà può essere creata dall'attività CreateProperty. Questo tipo di utilizzo è deprecato.
A partire da .NET Framework 3.5, gli elementi Target possono contenere elementi PropertyGroup che possono contenere a loro volta dichiarazioni di proprietà.

Archiviazione di XML nelle proprietà

Le proprietà possono contenere codice XML arbitrario, che può risultare utile per il passaggio dei valori alle attività o per la visualizzazione delle informazioni di registrazione. Nell'esempio seguente viene illustrata la proprietà ConfigTemplate che dispone di un valore che contiene codice XML e altri riferimenti alle proprietà. In MSBuild i riferimenti alle proprietà vengono sostituiti con i rispettivi valori delle proprietà. I valori delle proprietà vengono assegnati in base all'ordine in cui appaiono. In questo esempio, pertanto, $(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>

Vedere anche

Condividi tramite