.vcxproj e .props struttura dei file

MSBuild è il sistema di progetto predefinito in Visual Studio. Quando si sceglie File>Nuovo progetto in Visual C++ si sta creando un progetto MSBuild le cui impostazioni vengono archiviate in un file di progetto XML con estensione ..vcxproj Il file di progetto può anche importare file e .targets file in cui è possibile archiviare .props le impostazioni.

Se si intende mantenere le proprietà del progetto nell'IDE, è consigliabile creare e modificare solo i .vcxproj progetti nell'IDE ed evitare modifiche manuali ai file. Nella maggior parte dei casi, non è mai necessario modificare manualmente il file di progetto. Le modifiche manuali possono interrompere le connessioni di progetto necessarie per modificare le impostazioni del progetto nelle pagine delle proprietà di Visual Studio e possono causare errori di compilazione difficili da eseguire durante il debug e il ripristino. Per altre informazioni sull'uso delle pagine delle proprietà, vedere Impostare il compilatore C++ e le proprietà di compilazione in Visual Studio.

Su larga scala, la gestione di molti singoli progetti nell'IDE diventa noiosa e soggetta a errori. È difficile mantenere la coerenza o applicare la standardizzazione tra decine o centinaia di progetti. In questi casi, è consigliabile modificare i file di progetto per usare file personalizzati .props o .targets per proprietà comuni in molti progetti. È anche possibile usare questi file quando sono necessarie personalizzazioni che non sono possibili nell'IDE. I punti utili per inserire le personalizzazioni sono i Directory.Build.props file e Directory.Build.targets , che vengono importati automaticamente in tutti i progetti basati su MSBuild.

In alcuni casi, i file personalizzati .props o .targets da soli potrebbero non essere sufficienti per le esigenze di gestione del progetto. Potrebbe comunque essere necessario modificare .vcxproj manualmente i file di progetto o le finestre delle proprietà. La modifica manuale richiede una buona conoscenza di MSBuild e deve seguire le linee guida in questo articolo. Per consentire all'IDE di caricare e aggiornare .vcxproj automaticamente i file, questi file presentano diverse restrizioni che non si applicano ad altri file di progetto MSBuild. Gli errori possono causare l'arresto anomalo o il comportamento dell'IDE in modi imprevisti.

Per gli scenari di modifica manuale, questo articolo contiene informazioni di base sulla struttura dei .vcxproj file correlati e .

Considerazioni importanti

Se si sceglie di modificare manualmente un .vcxproj file, tenere presente questi fatti:

• La struttura del file deve seguire una forma prescritta, come descritto in questo articolo.

• Il sistema di progetto C++ di Visual Studio attualmente non supporta caratteri jolly o elenchi direttamente negli elementi del progetto. Ad esempio, questi moduli non sono supportati:

  <ItemGroup>
     <None Include="*.txt"/>
     <ClCompile Include="a.cpp;b.cpp"/>
  </ItemGroup>
  

  Per altre informazioni sul supporto dei caratteri jolly nei progetti e sulle possibili soluzioni alternative, vedere .vcxproj file e caratteri jolly.

• Il sistema di progetto C++ di Visual Studio attualmente non supporta le macro nei percorsi degli elementi del progetto. Ad esempio, questo modulo non è supportato:

  <ItemGroup>
     <ClCompile Include="$(IntDir)\generated.cpp"/>
  </ItemGroup>
  

  "Non supportato" indica che le macro non sono garantite per tutte le operazioni nell'IDE. Le macro che non modificano il valore in configurazioni diverse devono funzionare, ma potrebbero non essere mantenute se un elemento viene spostato in un altro filtro o progetto. Le macro che modificano il valore per configurazioni diverse causeranno problemi. L'IDE non prevede che i percorsi degli elementi del progetto siano diversi per configurazioni di progetto diverse.

• Per aggiungere, rimuovere o modificare correttamente le proprietà del progetto quando vengono modificate nella finestra di dialogo Proprietà progetto, il file deve contenere gruppi separati per ogni configurazione del progetto. Le condizioni devono essere in questo formato:

  Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'"
  

• Ogni proprietà deve essere specificata nel gruppo con l'etichetta corretta, come specificato nel file della regola di proprietà. Per altre informazioni, vedere File delle regole XML della Pagina delle proprietà.

.vcxproj elementi di file

È possibile esaminare il contenuto di un .vcxproj file utilizzando qualsiasi editor di testo o XML. Per visualizzare il file in Visual Studio, fare clic con il pulsante destro del mouse sul progetto in Esplora soluzioni, scegliere Scarica progetto e quindi Modifica Foo.vcxproj.

Il primo aspetto da notare è che gli elementi di primo livello sono visualizzati in un ordine particolare. Ad esempio:

• La maggior parte dei gruppi di proprietà e di definizioni elementi viene visualizzata dopo l'importazione per Microsoft.Cpp.Default.props.

• Tutte le destinazioni vengono importate alla fine del file.

• Sono presenti più gruppi di proprietà, ognuno con un'etichetta univoca, visualizzati in un ordine particolare.

L'ordine degli elementi nel file di progetto è fondamentale, perché MSBuild è basato su un modello di valutazione sequenziale. Se il file di progetto, inclusi tutti i file e .targets importati.props, è costituito da più definizioni di una proprietà, l'ultima definizione sostituisce quelle precedenti. Nell'esempio seguente, il valore "xyz" verrà impostato durante la compilazione perché il motore MSB Compilationd lo rileva per ultimo durante la valutazione.

  <MyProperty>abc</MyProperty>
  <MyProperty>xyz</MyProperty>

Il frammento di codice seguente mostra un file minimo .vcxproj . Qualsiasi .vcxproj file generato da Visual Studio conterrà questi elementi MSBuild di primo livello. E appariranno in questo ordine, anche se possono contenere più copie di ogni elemento di primo livello. Tutti Label gli attributi sono tag arbitrari usati solo da Visual Studio come segnaposto per la modifica. Non hanno altre funzioni.

<Project DefaultTargets="Build" ToolsVersion="4.0" xmlns='http://schemas.microsoft.com/developer/msbuild/2003'>
  <ItemGroup Label="ProjectConfigurations" />
  <PropertyGroup Label="Globals" />
  <Import Project="$(VCTargetsPath)\Microsoft.Cpp.default.props" />
  <PropertyGroup Label="Configuration" />
  <Import Project="$(VCTargetsPath)\Microsoft.Cpp.props" />
  <ImportGroup Label="ExtensionSettings" />
  <ImportGroup Label="PropertySheets" />
  <PropertyGroup Label="UserMacros" />
  <PropertyGroup />
  <ItemDefinitionGroup />
  <ItemGroup />
  <Import Project="$(VCTargetsPath)\Microsoft.Cpp.targets" />
  <ImportGroup Label="ExtensionTargets" />
</Project>

Le sezioni seguenti descrivono lo scopo di ognuno di questi elementi e perché vengono ordinati in questo modo:

Elemento Project

<Project DefaultTargets="Build" ToolsVersion="4.0" xmlns='http://schemas.microsoft.com/developer/msbuild/2003' >

Project è il nodo radice. Specifica la versione di MSBuild da usare e la destinazione predefinita da eseguire quando questo file viene passato a MSBuild.exe.

Elemento ItemGroup ProjectConfigurations

<ItemGroup Label="ProjectConfigurations" />

ProjectConfigurations contiene la descrizione della configurazione del progetto. Ad esempio, Debug|Win32, Release|Win32, Debug|ARM e così via. Molte impostazioni di progetto sono specifiche di una determinata configurazione. Ad esempio, è probabile che si voglia impostare le proprietà di ottimizzazione per una build di versione, ma non una compilazione di debug.

Il ProjectConfigurations gruppo di elementi non viene usato in fase di compilazione. L'IDE di Visual Studio richiede il caricamento del progetto. Questo gruppo di elementi può essere spostato in un .props file e importato nel .vcxproj file. Tuttavia, in tal caso, se è necessario aggiungere o rimuovere configurazioni, è necessario modificare manualmente il .props file. Non è possibile usare l'IDE.

Elementi ProjectConfiguration

Il frammento di codice seguente illustra la configurazione di un progetto. In questo esempio "Debug|x64" è il nome della configurazione. Il nome della configurazione del progetto deve essere nel formato $(Configuration)|$(Platform). Un ProjectConfiguration nodo può avere due proprietà: Configuration e Platform. Queste proprietà vengono impostate automaticamente con i valori specificati qui quando la configurazione è attiva.

<ProjectConfiguration Include="Debug|x64">
  <Configuration>Debug</Configuration>
  <Platform>x64</Platform>
</ProjectConfiguration>

L'IDE prevede di trovare una configurazione del progetto per qualsiasi combinazione di Configuration valori e Platform usati in tutti gli ProjectConfiguration elementi. Spesso, significa che un progetto potrebbe avere configurazioni di progetto senza significato per soddisfare questo requisito. Se, ad esempio, un progetto include queste configurazioni:

• Debug|Win32

• Retail|Win32

• Special 32-bit Optimization|Win32

dovrà includere anche queste configurazioni, sebbene "Special 32-bit Optimization" non sia una configurazione significativa per x64:

• Debug|x64

• Retail|x64

• Special 32-bit Optimization|x64

È possibile disabilitare i comandi di compilazione e distribuzione per qualsiasi configurazione in Gestione configurazione della soluzione.

Elemento PropertyGroup Globals

<PropertyGroup Label="Globals" />

Globals contiene impostazioni a livello di progetto, ad ProjectGuidesempio , RootNamespacee ApplicationType o ApplicationTypeRevision. Le ultime due spesso definiscono il sistema operativo di destinazione. Un progetto può avere come destinazione un singolo sistema operativo perché attualmente i riferimenti e gli elementi del progetto non possono avere condizioni. Di queste proprietà non viene in genere eseguito l'override in altre posizioni nel file di progetto. Questo gruppo non è dipendente dalla configurazione e in genere esiste solo un Globals gruppo nel file di progetto.

Elemento Import Microsoft.Cpp.default.props

<Import Project="$(VCTargetsPath)\Microsoft.Cpp.default.props" />

La finestra delle proprietà Microsoft.Cpp.default.props viene fornita con Visual Studio e non può essere modificata. Contiene le impostazioni predefinite del progetto. Le impostazioni predefinite possono variare, a seconda di ApplicationType.

Elementi PropertyGroup Configuration

<PropertyGroup Label="Configuration" />

Un gruppo di proprietà Configuration ha una condizione di configurazione associata (ad esempio, Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'") ed è disponibile in più copie, una per configurazione. Questo gruppo di proprietà ospita le proprietà impostate per una configurazione specifica. Le proprietà di configurazione includono PlatformToolset e controllano anche l'inclusione delle finestre delle proprietà di sistema in Microsoft.Cpp.props. Ad esempio, se si definisce la proprietà <CharacterSet>Unicode</CharacterSet>, verrà inclusa la finestra delle proprietà di sistema microsoft.Cpp.unicodesupport.props. Se si esamina Microsoft.Cpp.props, verrà visualizzata la riga : <Import Condition="'$(CharacterSet)' == 'Unicode'" Project="$(VCTargetsPath)\microsoft.Cpp.unicodesupport.props" />.

Elemento Import Microsoft.Cpp.props

<Import Project="$(VCTargetsPath)\Microsoft.Cpp.props" />

La finestra delle proprietà Microsoft.Cpp.props (direttamente o tramite importazioni) definisce i valori predefiniti per molte proprietà specifiche dello strumento. Gli esempi includono le proprietà Optimization e Warning Level del compilatore, la proprietà TypeLibraryName dello strumento MIDL e così via. Importa anche varie finestre delle proprietà di sistema in base alle proprietà di configurazione definite nel gruppo di proprietà immediatamente prima.

Elemento ImportGroup ExtensionSettings

<ImportGroup Label="ExtensionSettings" />

Il gruppo ExtensionSettings contiene importazioni per le finestre delle proprietà che fanno parte delle personalizzazioni delle compilazioni. Una personalizzazione della compilazione è definita da un massimo di tre file: un .targets file, un .props file e un .xml file. Questo gruppo di importazione contiene le importazioni per il .props file.

Elementi ImportGroup PropertySheets

<ImportGroup Label="PropertySheets" />

Il gruppo PropertySheets contiene le importazioni per le finestre delle proprietà utente, Queste importazioni sono le finestre delle proprietà aggiunte tramite la visualizzazione Gestione proprietà in Visual Studio. L'ordine in cui sono elencate queste importazioni è importante ed è riportato in Gestione proprietà. Il file di progetto normalmente contiene più istanze di questo tipo di gruppo di importazioni, una per ogni configurazione di progetto.

Elemento PropertyGroup UserMacros

<PropertyGroup Label="UserMacros" />

UserMacros contiene proprietà create come variabili che vengono usate per personalizzare il processo di compilazione. È possibile, ad esempio, definire una macro utente per definire un percorso di output personalizzato come $(CustomOutputPath) e usarla per definire altre variabili. Questo gruppo di proprietà ospita queste proprietà. In Visual Studio questo gruppo non viene popolato nel file di progetto perché Visual C++ non supporta le macro utente per le configurazioni. Le macro utente sono supportate nelle finestre delle proprietà.

Elementi PropertyGroup a livello di singola configurazione

<PropertyGroup />

Esistono più istanze di questo gruppo di proprietà, una per configurazione per tutte le configurazioni di progetto. Ogni gruppo di proprietà deve avere una condizione di configurazione associata. Se una configurazione risulta mancante, la finestra di dialogo Proprietà progetto non funzionerà correttamente. A differenza dei gruppi di proprietà elencati in precedenza, questo non ha un'etichetta. Esso contiene le impostazioni a livello di configurazione di progetto. Queste impostazioni si applicano a tutti i file che fanno parte del gruppo di elementi specificato. I metadati delle definizioni degli elementi della personalizzazione compilazioni vengono inizializzati qui.

Questo PropertyGroup deve venire dopo <Import Project="$(VCTargetsPath)\Microsoft.Cpp.props" /> e non deve essere presente alcun altro PropertyGroup senza un'etichetta prima di esso ( in caso contrario, la modifica delle proprietà del progetto non funzionerà correttamente).

Elementi ItemDefinitionGroup a livello di singola configurazione

<ItemDefinitionGroup />

Contiene le definizioni degli elementi Queste definizioni devono seguire le stesse regole delle condizioni degli elementi di configurazione PropertyGroup senza etichetta.

Elementi ItemGroup

<ItemGroup />

ItemGroup gli elementi contengono gli elementi (file di origine e così via) nel progetto. Le condizioni non sono supportate per gli elementi di Project, ovvero i tipi di elemento considerati come elementi del progetto in base alle definizioni delle regole.

I metadati devono avere condizioni di configurazione per ogni configurazione, anche se sono tutte uguali. Ad esempio:

<ItemGroup>
  <ClCompile Include="stdafx.cpp">
    <TreatWarningAsError Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'">true</TreatWarningAsError>
    <TreatWarningAsError Condition="'$(Configuration)|$(Platform)'=='Debug|x64'">true</TreatWarningAsError>
  </ClCompile>
</ItemGroup>

Il sistema di progetto C++ di Visual Studio attualmente non supporta i caratteri jolly negli elementi del progetto.

<ItemGroup>
  <ClCompile Include="*.cpp"> <!--Error-->
</ItemGroup>

Il sistema di progetto C++ di Visual Studio attualmente non supporta le macro negli elementi del progetto.

<ItemGroup>
  <ClCompile Include="$(IntDir)\generated.cpp"> <!--not guaranteed to work in all scenarios-->
</ItemGroup>

I riferimenti sono specificati in un elemento ItemGroup e prevedono le limitazioni seguenti:

• I riferimenti non supportano le condizioni.

• I metadati dei riferimenti non supportano le condizioni.

Elemento Import Microsoft.Cpp.targets

<Import Project="$(VCTargetsPath)\Microsoft.Cpp.targets" />

Definisce (direttamente o tramite importazioni) destinazioni C++ come compilazione, pulizia e così via.

Elemento ImportGroup ExtensionTargets

<ImportGroup Label="ExtensionTargets" />

Questo gruppo contiene le importazioni per i file di destinazione della personalizzazione compilazioni.

Conseguenze dell'ordinamento errato

L'IDE di Visual Studio dipende dal file di progetto con l'ordinamento descritto in precedenza. Ad esempio, quando si definisce il valore di una proprietà nelle pagine delle proprietà, l'IDE inserisce in genere la definizione della proprietà nel gruppo di proprietà con l'etichetta vuota. Questo ordinamento garantisce che i valori predefiniti inseriti nelle finestre delle proprietà di sistema vengano sostituiti da valori definiti dall'utente. Analogamente, i file di destinazione vengono importati alla fine perché usano le proprietà definite in precedenza e poiché in genere non definiscono le proprietà stesse. Analogamente, le finestre delle proprietà utente vengono importate dopo le finestre delle proprietà di sistema (incluse da Microsoft.Cpp.props). Questo ordine garantisce che l'utente possa eseguire l'override di qualsiasi impostazione predefinita inserita dalle finestre delle proprietà di sistema.

Se un .vcxproj file non segue questo layout, i risultati della compilazione potrebbero non essere quello previsto. Ad esempio, se si importa erroneamente una finestra delle proprietà di sistema dopo le finestre delle proprietà definite dall'utente, le impostazioni utente vengono sostituite dalle finestre delle proprietà di sistema.

Anche l'esperienza in fase di progettazione dell'IDE dipende da un certo grado di ordinamento corretto degli elementi. Ad esempio, se il .vcxproj file non ha il PropertySheets gruppo di importazione, l'IDE potrebbe non essere in grado di determinare dove posizionare una nuova finestra delle proprietà creata dall'utente in Gestione proprietà. Potrebbe comportare l'override di un foglio utente da parte di un foglio di sistema. Anche se l'euristica usata dall'IDE può tollerare piccole incoerenze nel layout del .vcxproj file, è consigliabile non deviare dalla struttura illustrata in precedenza in questo articolo.

Uso delle etichette dell'elemento da parte dell'IDE

Nell'IDE, quando si imposta la proprietà UseOfAtl nella pagina delle proprietà generale, viene scritta nel gruppo di proprietà Configuration nel file di progetto. La proprietà TargetName nella stessa pagina delle proprietà viene scritta nel gruppo di proprietà senza etichetta per configurazione. Visual Studio cerca le informazioni sulla posizione in cui scrivere ogni proprietà nel file XML della pagina delle proprietà. Per la pagina delle proprietà Generale, presupponendo che sia disponibile una versione inglese di Visual Studio 2019 edizione Enterprise, tale file è %ProgramFiles(x86)%\Microsoft Visual Studio\2019\Enterprise\Common7\IDE\VC\VCTargets\1033\general.xml. Il file delle regole XML della pagina delle proprietà definisce le informazioni statiche su una regola e tutte le relative proprietà. Queste informazioni sono la posizione preferita di una proprietà Rule nel file di destinazione (il file in cui verrà scritto il relativo valore). La posizione preferita è specificata dall'attributo Label sugli elementi del file di progetto.

Layout della finestra delle proprietà

Il frammento XML seguente è un layout minimo del file (con estensione props) di una finestra delle proprietà. È simile a un .vcxproj file e la funzionalità degli .props elementi può essere dedotta dalla discussione precedente.

<Project ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
  <ImportGroup Label="PropertySheets" />
  <PropertyGroup Label="UserMacros" />
  <PropertyGroup />
  <ItemDefinitionGroup />
  <ItemGroup />
</Project>

Per creare una finestra delle proprietà personalizzata, copiare uno dei .props file nella cartella e modificarlo ai fini dell'utente VCTargets . Per Visual Studio 2019 Enterprise Edition, il percorso predefinito VCTargets è %ProgramFiles%\Microsoft Visual Studio\2019\Enterprise\Common7\IDE\VC\VCTargets.

Vedi anche

Impostare le proprietà del compilatore e di compilazione C++ in Visual Studio
File XML delle pagine delle proprietà
.vcxproj file e caratteri jolly