proprietà di MSBuildMSBuild properties

Le proprietà sono coppie nome-valore che possono essere usate per configurare le compilazioni.Properties are name-value pairs that can be used to configure builds. 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.Properties are useful for passing values to tasks, evaluating conditions, and storing values that will be referenced throughout the project file.

Definire e fare riferimento alle proprietà in un file di progettoDefine and reference properties in a project file

Per dichiarare le proprietà, è necessario creare un elemento con lo stesso nome della proprietà, come figlio di un elemento PropertyGroup.Properties are declared by creating an element that has the name of the property as a child of a PropertyGroup element. l codice XML seguente, ad esempio, crea una proprietà denominata BuildDir con un valore Build.For example, the following XML creates a property named BuildDir that has a value of Build.

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

Nel file di progetto, per fare riferimento alle proprietà, si usa la sintassi $(<PropertyName>).Throughout the project file, properties are referenced by using the syntax $(<PropertyName>). Ad esempio, per fare riferimento alla proprietà nell'esempio precedente, si usa $(BuildDir).For example, the property in the previous example is referenced by using $(BuildDir).

I valori delle proprietà possono essere modificati ridefinendo la proprietà.Property values can be changed by redefining the property. È possibile assegnare un nuovo valore alla proprietà BuildDir usando questo codice XML:The BuildDir property can be given a new value by using this XML:

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

Le proprietà vengono valutate nell'ordine in cui sono visualizzate nel file di progetto.Properties are evaluated in the order in which they appear in the project file. Il nuovo valore per BuildDir deve essere dichiarato dopo che è stato assegnato il valore precedente.The new value for BuildDir must be declared after the old value is assigned.

Proprietà riservateReserved properties

In MSBuild alcuni nomi di proprietà sono riservati per archiviare le informazioni relative al file di progetto e ai file binari di MSBuild.MSBuild reserves some property names to store information about the project file and the MSBuild binaries. Per fare riferimento a queste proprietà, si usa la notazione $, come per qualsiasi altra proprietà.These properties are referenced by using the $ notation, just like any other property. Ad esempio, $(MSBuildProjectFile) restituisce il nome file completo del file di progetto, inclusa l'estensione di file.For example, $(MSBuildProjectFile) returns the complete file name of the project file, including the file name extension.

Per altre informazioni, vedere Procedura: Fare riferimento al nome o al percorso del file di progetto e Proprietà riservate e note di MSBuild.For more information, see How to: Reference the name or location of the project file and MSBuild reserved and well-known properties.

Proprietà dell'ambienteEnvironment properties

È possibile fare riferimento alle variabili di ambiente nei file di progetto esattamente come si fa riferimento alle proprietà riservate.You can reference environment variables in project files just as you reference reserved properties. Ad esempio, per usare la variabile di ambiente PATH nel file di progetto, usare $(Path).For example, to use the PATH environment variable in your project file, use $(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.If the project contains a property definition that has the same name as an environment property, the property in the project overrides the value of the environment variable.

A ogni progetto MSBuild è associato un blocco di ambiente isolato: nel relativo blocco personalizzato sono visualizzate solo le letture e le scritture.Each MSBuild project has an isolated environment block: it only sees reads and writes to its own block. 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.MSBuild only reads environment variables when it initializes the property collection, before the project file is evaluated or built. Successivamente, le proprietà dell'ambiente sono statiche, cioè ciascuno strumento generato inizia con gli stessi nomi e valori.After that, environment properties are static, that is, each spawned tool starts with the same names and values.

Per ottenere il valore corrente delle variabili di ambiente dall'interno di uno strumento generato, usare le funzioni di proprietà System.Environment.GetEnvironmentVariable.To get the current value of environment variables from within a spawned tool, use the Property functions System.Environment.GetEnvironmentVariable. Il metodo consigliato, tuttavia, consiste nell'utilizzare il parametro dell'attività EnvironmentVariables.The preferred method, however, is to use the task parameter 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.Environment properties set in this string array can be passed to the spawned tool without affecting the system environment variables.

Tip

Non tutte le variabili di ambiente vengono lette per diventare proprietà iniziali.Not all environment variables are read in to become initial properties. Tutte le variabili di ambiente il cui nome non è un nome di proprietà MSBuild valido, ad esempio "386", vengono ignorate.Any environment variable whose name is not a valid MSBuild property name, such as "386", is ignored.

Per altre informazioni, vedere Procedura: Usare le variabili di ambiente in una compilazione.For more information, see How to: Use environment variables in a build.

Proprietà del Registro di sistemaRegistry properties

È 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.You can read system registry values by using the following syntax, where Hive is the registry hive (for example, HKEY_LOCAL_MACHINE), MyKey is the key name, MySubKey is the subkey name, and Value is the value of the subkey.

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

Per ottenere il valore della sottochiave predefinito, omettere Value.To get the default subkey value, omit the Value.

$(registry:Hive\MyKey\MySubKey)

Questo valore del Registro di sistema può essere usato per inizializzare una proprietà di compilazione.This registry value can be used to initialize a build property. Ad esempio, per creare una proprietà di compilazione che rappresenta la home page del Web browser di Visual Studio, usare questo codice:For example, to create a build property that represents the Visual Studio web browser home page, use this code:

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

Proprietà globaliGlobal properties

MSBuild permette di impostare le proprietà nella riga di comando usando l'opzione -property (o -p).MSBuild lets you set properties on the command line by using the -property (or -p) switch. Questi valori delle proprietà globali eseguono l'override dei valori delle proprietà impostati nel file di progetto.These global property values override property values that are set in the project file. incluse le proprietà di ambiente, ma non le proprietà riservate, che non possono essere modificate.This includes environment properties, but does not include reserved properties, which cannot be changed.

L'esempio seguente imposta la proprietà Configuration globale su DEBUG.The following example sets the global Configuration property to 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.Global properties can also be set or modified for child projects in a multi-project build by using the Properties attribute of the MSBuild task. 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.Global properties are also forwarded to child projects unless the RemoveProperties attribute of the MSBuild task is used to specify the list of properties not to forward. Per altre informazioni, vedere Attività MSBuild.For more information, see MSBuild task.

Se si specifica una proprietà utilizzando l'attributo TreatAsLocalProperty in un tag di progetto, con il valore di quella proprietà globale non verrà sovrascritto il valore della proprietà impostata nel file di progetto.If you specify a property by using the TreatAsLocalProperty attribute in a project tag, that global property value doesn't override the property value that's set in the project file. Per altre informazioni, vedere Elemento Project (MSBuild) e Procedura: Compilare gli stessi file di origine con opzioni diverse.For more information, see Project element (MSBuild) and How to: Build the same source files with different options.

Funzioni delle proprietàProperty functions

A partire da .NET Framework versione 4 è possibile utilizzare funzioni delle proprietà per valutare gli script MSBuild.Starting in .NET Framework version 4, you can use property functions to evaluate your MSBuild scripts. È 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.You can read the system time, compare strings, match regular expressions, and perform many other actions within your build script without using MSBuild tasks.

È possibile usare metodi di stringa (istanza) per operare su qualsiasi valore della proprietà ed è possibile chiamare i metodi statici di diverse classi di sistema.You can use string (instance) methods to operate on any property value, and you can call the static methods of many system classes. È ad esempio possibile impostare una proprietà di compilazione sulla data odierna come segue.For example, you can set a build property to today's date as follows.

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

Per altre informazioni e per un elenco di funzioni delle proprietà, vedere Funzioni delle proprietà.For more information, and a list of property functions, see Property functions.

Creare proprietà durante l'esecuzioneCreate properties during execution

Alle proprietà non comprese in elementi Target vengono assegnati valori durante la fase di valutazione di una compilazione.Properties positioned outside Target elements are assigned values during the evaluation phase of a build. Durante la fase di esecuzione successiva, le proprietà possono essere create o modificate come segue:During the subsequent execution phase, properties can be created or modified as follows:

  • Una proprietà può essere creata da qualsiasi attività.A property can be emitted by any task. Per creare una proprietà, l'elemento Task deve avere un elemento Output figlio con un attributo PropertyName.To emit a property, the Task element must have a child Output element that has a PropertyName attribute.

  • Una proprietà può essere creata dall'attività CreateProperty.A property can be emitted by the CreateProperty task. Questo utilizzo è deprecato.This usage is deprecated.

  • A partire da .NET Framework 3.5, gli elementi Target possono contenere elementi PropertyGroup che possono contenere dichiarazioni di proprietà.Starting in the .NET Framework 3.5, Target elements may contain PropertyGroup elements that may contain property declarations.

Archiviare codice XML nelle proprietàStore XML in properties

Le proprietà possono contenere codice XML arbitrario, che consente di passare i valori alle attività o di visualizzare le informazioni di registrazione.Properties can contain arbitrary XML, which can help in passing values to tasks or displaying logging information. L'esempio seguente illustra la proprietà ConfigTemplate, che ha un valore contenente codice XML e riferimenti ad altre proprietà.The following example shows the ConfigTemplate property, which has a value that contains XML and other property references. MSBuildMSBuild sostituisce i riferimenti alle proprietà con i rispettivi valori delle proprietà.replaces the property references by using their respective property values. I valori delle proprietà vengono assegnati nell'ordine in cui sono visualizzati.Property values are assigned in the order in which they appear. In questo esempio quindi $(MySupportedVersion), $(MyRequiredVersion) e $(MySafeMode) devono essere già stati definiti.Therefore, in this example, $(MySupportedVersion), $(MyRequiredVersion), and $(MySafeMode) should have already been defined.

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

Vedere ancheSee also