File XML delle pagine delle proprietà

Le pagine delle proprietà del progetto nell'IDE vengono configurate dai file XML nella cartella delle regole predefinite. I file XML descrivono i nomi delle regole, le categorie e le singole proprietà, il tipo di dati, i valori predefiniti e come visualizzarli. Quando si imposta una proprietà nell'IDE, il nuovo valore viene archiviato nel file di progetto.

Il percorso della cartella delle regole predefinite dipende dalle impostazioni locali e dalla versione di Visual Studio in uso. In un prompt dei comandi per sviluppatori di Visual Studio 2019 o versione successiva, la cartella rules è %VSINSTALLDIR%MSBuild\Microsoft\VC\<version>\<locale>\, dove il <version> valore si trova v160 in Visual Studio 2019. <locale> è un LCID, ad esempio, 1033 per l'inglese. In Visual Studio 2017 la cartella rules è %VSINSTALLDIR%Common7\IDE\VC\VCTargets\<locale>\. In un prompt dei comandi di Visual Studio 2015 o versioni precedenti, la cartella rules è %ProgramFiles(x86)%\MSBuild\Microsoft.Cpp\v4.0\<version>\<locale>\. Si userà un percorso diverso per ogni edizione di Visual Studio installata e per ogni lingua. Ad esempio, il percorso predefinito della cartella delle regole per Visual Studio 2019 Community Edition in inglese potrebbe essere C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\MSBuild\Microsoft\VC\v160\1033\.

È sufficiente comprendere le operazioni interne di questi file e l'IDE di Visual Studio in due scenari:

• Si vuole creare una pagina delle proprietà personalizzata o
• Si vuole personalizzare le proprietà del progetto senza usare l'IDE di Visual Studio.

Contenuto dei file delle regole

Aprire prima di tutto le pagine delle proprietà per un progetto. Fare clic con il pulsante destro del mouse sul nodo del progetto in Esplora soluzioni e scegliere Proprietà:

Ogni nodo in Proprietà di configurazione è denominato regola. Una regola a volte rappresenta un singolo strumento come il compilatore. In generale, il termine si riferisce a un elemento con proprietà, che viene eseguito e che può produrre un output. Ogni regola viene popolata da un file XML nella cartella delle regole predefinite. Ad esempio, la regola C/C++ illustrata di seguito viene popolata da cl.xml.

Ogni regola ha un set di proprietà, organizzate in categorie. Ogni sottonodo in una regola rappresenta una categoria. Ad esempio, il nodo Ottimizzazione in C/C++ contiene tutte le proprietà correlate all'ottimizzazione dello strumento del compilatore. Le proprietà e i relativi valori vengono visualizzati in un formato griglia nel riquadro destro.

È possibile aprire cl.xml nel Blocco note o in qualsiasi editor XML. Verrà visualizzato un nodo radice denominato Rule. Definisce lo stesso elenco di proprietà che vengono visualizzate nell'interfaccia utente, insieme ai metadati aggiuntivi.

<?xml version="1.0" encoding="utf-8"?>
<!--Copyright, Microsoft Corporation, All rights reserved.-->
<Rule Name="CL" PageTemplate="tool" DisplayName="C/C++" SwitchPrefix="/" Order="10" xmlns="http://schemas.microsoft.com/build/2009/properties" xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" xmlns:sys="clr-namespace:System;assembly=mscorlib">
  <Rule.Categories>
    <Category Name="General" DisplayName="General" />
    <Category Name="Optimization" DisplayName="Optimization" />
    <Category Name="Preprocessor" DisplayName="Preprocessor" />
    <Category Name="Code Generation" DisplayName="Code Generation" />
    <Category Name="Language" DisplayName="Language" />
    <Category Name="Precompiled Headers" DisplayName="Precompiled Headers" />
    <Category Name="Output Files" DisplayName="Output Files" />
    <Category Name="Browse Information" DisplayName="Browse Information" />
    <Category Name="Advanced" DisplayName="Advanced" />
    <Category Name="All Options" DisplayName="All Options" Subtype="Search" />
    <Category Name="Command Line" DisplayName="Command Line" Subtype="CommandLine" />
  </Rule.Categories>
  <!-- . . . -->
</Rule>

Esiste un file XML per ogni nodo in Proprietà di configurazione nell'interfaccia utente delle pagine delle proprietà. È possibile aggiungere o rimuovere regole nell'interfaccia utente. Questa operazione viene eseguita includendo o rimuovendo percorsi ai file XML corrispondenti nel progetto. Ad esempio, è come Microsoft.CppBuild.targets (trovato un livello superiore alla cartella 1033) include cl.xml:

<PropertyPageSchema Condition="'$(ConfigurationType)' != 'Utility'" Include="$(VCTargetsPath)$(LangID)\cl.xml"/>

Se si esegue lo strip cl.xml di tutti i dati, si dispone di questo framework di base:

<?xml version="1.0" encoding="utf-8"?>
<Rule>
  <Rule.DataSource />
  <Rule.Categories>
    <Category />
    <!-- . . . -->
  </Rule.Categories>
  <BoolProperty />
  <EnumProperty />
  <IntProperty />
  <StringProperty />
  <StringListProperty />
</Rule>

La sezione successiva descrive ogni elemento principale e alcuni dei metadati che è possibile collegare.

Attributi delle regole

Un <Rule> elemento è il nodo radice nel file XML. Può avere molti attributi:

<Rule Name="CL" PageTemplate="tool" SwitchPrefix="/" Order="10"
          xmlns="http://schemas.microsoft.com/build/2009/properties"
          xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
          xmlns:sys="clr-namespace:System;assembly=mscorlib">
  <Rule.DisplayName>
    <sys:String>C/C++</sys:String>
  </Rule.DisplayName>

• Name: l'attributo Name è un ID per .Rule Deve essere univoco tra tutti i file XML della pagina delle proprietà per un progetto.

• PageTemplate: il valore di questo attributo viene usato dall'interfaccia utente per scegliere tra una raccolta di modelli di interfaccia utente. Il modello "tool" esegue il rendering delle proprietà sotto forma di griglia standard. Altri valori predefiniti per questo attributo sono "debugger" e "generic". Vedere rispettivamente il nodo Debug e Generale per visualizzare il formato dell'interfaccia utente risultante dall'impostazione di questi valori. Il modello di pagina dell'interfaccia utente per il "debugger" usa una casella di riepilogo a discesa per passare tra le proprietà di debugger diversi. Il modello "generico" visualizza categorie di proprietà diverse in una pagina, anziché avere più sottonodi categoria nel Rule nodo. Questo attributo è solo un suggerimento per l'interfaccia utente. Il file XML è progettato per essere indipendente dall'interfaccia utente. Un'altra interfaccia utente potrebbe usare questo attributo per scopi diversi.

• SwitchPrefix: prefisso usato nella riga di comando per le opzioni. Un valore di "/" genererebbe opzioni simili /ZIa , /nologo, /W3e così via.

• Order: suggerimento a un potenziale client dell'interfaccia utente nella posizione relativa di questo Rule rispetto a tutte le altre regole nel sistema.

• xmlns: elemento XML standard. È possibile visualizzare tre spazi dei nomi elencati, Questi attributi corrispondono rispettivamente agli spazi dei nomi per le classi di deserializzazione XML, XML Schema e lo spazio dei nomi di sistema.

• DisplayName: nome visualizzato nell'interfaccia utente della pagina delle proprietà per il Rule nodo. Questo valore non è localizzato. È stato creato DisplayName come elemento figlio di Rule anziché come attributo (ad esempio Name o SwitchPrefix) a causa dei requisiti interni dello strumento di localizzazione. Dal punto di vista XML, entrambi sono equivalenti. È quindi possibile trasformarlo in attributo per evitare confusione o lasciarlo invariato.

• DataSource: questa proprietà importante indica al sistema del progetto la posizione da leggere e scrivere il valore della proprietà e il relativo raggruppamento (illustrato più avanti). Per cl.xml, questi valori sono:

  <DataSource Persistence="ProjectFile" ItemType="ClCompile" Label="" HasConfigurationCondition="true" />
  

  • Persistence="ProjectFile" indica al sistema di progetto che tutte le proprietà per l'oggetto Rule devono essere scritte nel file di progetto o nel file della finestra delle proprietà (a seconda del nodo utilizzato per generare le pagine delle proprietà). L'altro valore possibile è "UserFile", che scriverà il valore nel .user file.

  • ItemType="ClCompile": indica che le proprietà saranno archiviate come metadati ItemDefinition o metadati degli elementi di questo tipo di elemento. Questo caso si verifica solo se le pagine delle proprietà sono state generate da un nodo del file in Esplora soluzioni. Se questo campo non è impostato, la proprietà viene scritta come proprietà comune in un PropertyGroup.

  • Label="": quando le proprietà sono scritte come metadati ItemDefinition, indica che l'etichetta dell'elemento padre ItemDefinitionGroup sarà vuota. Tutti gli elementi MSBuild possono avere un'etichetta. Visual Studio 2017 e versioni successive usano gruppi con etichette per esplorare il file di progetto con estensione vcxproj. I gruppi che contengono la maggior parte Rule delle proprietà hanno una stringa vuota come etichetta.

  • HasConfigurationCondition="true": indica al sistema del progetto di aggiungere una condizione di configurazione al valore in modo che sia applicato solo alla configurazione di progetto corrente. La condizione può essere aggiunta al gruppo padre o al valore stesso. Ad esempio, aprire le pagine delle proprietà dal nodo del progetto e impostare il valore della proprietà Considera avvisi come errore in Proprietà > di configurazione C/C++ Generale su "Sì". Il valore seguente viene scritto nel file di progetto. Si noti la condizione di configurazione associata all'elemento padre ItemDefinitionGroup.

    <ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'">
      <ClCompile>
        <TreatWarningAsError>true</TreatWarningAsError>
      </ClCompile>
    </ItemDefinitionGroup>
    

    Se questo valore viene impostato nella pagina delle proprietà per un file specifico, ad esempio stdafx.cpp, il valore della proprietà deve essere scritto sotto l'elemento stdafx.cpp nel file di progetto, come illustrato qui. Si noti che la condizione di configurazione viene collegata direttamente ai metadati stessi:

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

  Un altro attributo di DataSource non elencato di seguito è PersistedName. È possibile usare questo attributo per rappresentare una proprietà nel file di progetto usando un nome diverso. Per impostazione predefinita, questo attributo è impostato su Name.

  Una singola proprietà può eseguire l'override dell'oggetto DataSource del relativo elemento padre Rule. In tal caso, la posizione per il valore di tale proprietà sarà diversa da altre proprietà in Rule.

• Esistono altri attributi di un Ruleoggetto , incluso Description e SupportsFileBatching, che non sono visualizzati qui. È possibile ottenere il set completo di attributi applicabili a un Rule oggetto o su qualsiasi altro elemento esplorando la documentazione per questi tipi. In alternativa, è possibile esaminare le proprietà pubbliche nei tipi dello spazio dei nomi Microsoft.Build.Framework.XamlTypes nell'assembly Microsoft.Build.Framework.dll.

• DisplayName, PageTemplatee Order sono proprietà correlate all'interfaccia utente presenti in questo modello di dati indipendente dall'interfaccia utente. Queste sono quasi sicuramente le proprietà di tutte le interfacce utente usate per visualizzare le pagine delle proprietà. DisplayName e Description sono due proprietà presenti su quasi tutti gli elementi nel file XML. E, queste due proprietà sono le uniche localizzate.

Elementi categoria

Un Rule oggetto può avere più Category elementi. L'ordine in cui le categorie sono elencate nel file XML è un suggerimento all'interfaccia utente per visualizzare le categorie nello stesso ordine. Ad esempio, l'ordine delle categorie nel nodo C/C++ visualizzato nell'interfaccia utente è uguale all'ordine in cl.xml. Di seguito un esempio di categoria:

<Category Name="Optimization">
  <Category.DisplayName>
    <sys:String>Optimization</sys:String>
  </Category.DisplayName>
</Category>

Questo frammento mostra gli Name attributi e DisplayName descritti in precedenza. Ancora una volta, esistono altri attributi che non Category sono visualizzati nell'esempio. È possibile ottenere informazioni su di essi leggendo la documentazione o esaminando gli assembly usando ildasm.exe.

Elementi della proprietà

La maggior parte del file di regole è costituita da Property elementi. Contengono l'elenco di tutte le proprietà in un oggetto Rule. Ogni proprietà può essere uno dei cinque tipi possibili illustrati nel framework di base: BoolProperty, EnumPropertyIntProperty, StringProperty, e StringListProperty. Potrebbero essere presenti solo alcuni di questi tipi nel file. Una proprietà ha diversi attributi che consentono di descriverlo in dettaglio. La StringProperty classe è descritta qui. Il resto è simile.

<StringProperty Subtype="file" Name="ObjectFileName" Category="Output Files" Switch="Fo">
  <StringProperty.DisplayName>
    <sys:String>Object File Name</sys:String>
  </StringProperty.DisplayName>
  <StringProperty.Description>
    <sys:String>Specifies a name to override the default object file name; can be file or directory name.(/Fo[name])</sys:String>
  </StringProperty.Description>
</StringProperty>

La maggior parte degli attributi nel frammento di codice è stata descritta in precedenza. I nuovi sono Subtype, Categorye Switch.

• Subtype è un attributo disponibile solo per StringProperty gli elementi e StringListProperty . Fornisce informazioni contestuali. Ad esempio, il valore file indica che la proprietà rappresenta un percorso di file. Visual Studio usa tali informazioni contestuali per migliorare l'esperienza di modifica. Ad esempio, può fornire una finestra di Esplora risorse che consente all'utente di scegliere visivamente il file come editor della proprietà.

• Category: categoria con cui rientra questa proprietà. Provare a cercare questa proprietà nella categoria File di output nell'interfaccia utente.

• Switch: quando una regola rappresenta uno strumento come lo strumento del compilatore, la maggior parte Rule delle proprietà viene passata come commutatori all'eseguibile dello strumento in fase di compilazione. Il valore di questo attributo indica quale valore letterale cambiare da usare. Nell'esempio viene specificato che l'opzione <StringProperty> deve essere Fo. In combinazione con l'attributo nell'elemento SwitchPrefix padre Rule, questa proprietà viene passata all'eseguibile come /Fo"Debug\". È visibile nella riga di comando per C/C++ nell'interfaccia utente della pagina delle proprietà.

  Altri attributi della proprietà includono:

• Visible: se non si vuole che la proprietà venga visualizzata nelle pagine delle proprietà, ma si vuole che sia disponibile in fase di compilazione, impostare questo attributo su false.

• ReadOnly: se si desidera fornire una visualizzazione di sola lettura del valore di questa proprietà nelle pagine delle proprietà, impostare questo attributo su true.

• IncludeInCommandLine: in fase di compilazione, uno strumento potrebbe non avere bisogno di alcune delle relative proprietà. Impostare questo attributo su false per impedire che una determinata proprietà venga passata.