Soubory pravidel xml stránky vlastností

Stránky vlastností projektu v integrovaném vývojovém prostředí jsou nakonfigurovány soubory XML ve výchozí složce pravidel. Soubory XML popisují názvy pravidel, kategorií a jednotlivých vlastností, jejich datový typ, výchozí hodnoty a způsob jejich zobrazení. Při nastavení vlastnosti v integrovaném vývojovém prostředí (IDE) se nová hodnota uloží do souboru projektu.

Cesta k výchozí složce pravidel závisí na národním prostředí a používané verzi sady Visual Studio. Ve vývojářském příkazovém řádku sady Visual Studio 2019 nebo novějším je %VSINSTALLDIR%MSBuild\Microsoft\VC\<version>\<locale>\složka pravidel , kde <version> hodnota je v160 v sadě Visual Studio 2019. Jedná se <locale> například 1033 o LCID pro angličtinu. V sadě Visual Studio 2017 je %VSINSTALLDIR%Common7\IDE\VC\VCTargets\<locale>\složka pravidel . V sadě Visual Studio 2015 nebo starším vývojářském příkazovém řádku je %ProgramFiles(x86)%\MSBuild\Microsoft.Cpp\v4.0\<version>\<locale>\složka pravidel . Pro každou nainstalovanou edici sady Visual Studio a pro každý jazyk použijete jinou cestu. Například výchozí cesta ke složce pravidel pro edici Visual Studio 2019 Community v angličtině může být C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\MSBuild\Microsoft\VC\v160\1033\.

V několika scénářích stačí porozumět interním fungováním těchto souborů a integrovaného vývojového prostředí sady Visual Studio:

• Chcete vytvořit vlastní stránku vlastností nebo
• Chcete přizpůsobit vlastnosti projektu bez použití integrovaného vývojového prostředí sady Visual Studio.

Obsah souborů pravidel

Nejprve otevřete stránky vlastností projektu. Klikněte pravým tlačítkem myši na uzel projektu v Průzkumník řešení a zvolte Vlastnosti:

Každý uzel v části Vlastnosti konfigurace se nazývá pravidlo. Pravidlo někdy představuje jeden nástroj, jako je kompilátor. Obecně platí, že termín odkazuje na něco, co má vlastnosti, které se spouští a které mohou vytvořit nějaký výstup. Každé pravidlo se vyplní ze souboru XML ve složce výchozích pravidel. Například pravidlo C/C++, které je zde zobrazeno, je naplněno cl.xml.

Každé pravidlo má sadu vlastností, které jsou uspořádané do kategorií. Každý dílčí uzel pod pravidlem představuje kategorii. Například uzel Optimalizace v C /C++ obsahuje všechny vlastnosti související s optimalizací nástroje kompilátoru. Vlastnosti a jejich hodnoty se vykreslují ve formátu mřížky v pravém podokně.

Můžete otevřít cl.xml v poznámkovém bloku nebo v libovolném editoru XML. Zobrazí se kořenový uzel s názvem Rule. Definuje stejný seznam vlastností, které se zobrazí v uživatelském rozhraní, spolu s dalšími metadaty.

<?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>

V uživatelském rozhraní stránek vlastností je jeden soubor XML pro každý uzel v části Vlastnosti konfigurace. Pravidla můžete přidat nebo odebrat v uživatelském rozhraní: Provádí se zahrnutím nebo odebráním umístění do odpovídajících souborů XML v projektu. Například jak Microsoft.CppBuild.targets (nalezena jedna úroveň vyšší než složka 1033) zahrnuje cl.xml:

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

Pokud odstraníte cl.xml všechna data, máte tuto základní architekturu:

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

Další část popisuje každý hlavní prvek a některá metadata, která můžete připojit.

Atributy pravidla

Element <Rule> je kořenový uzel v souboru XML. Může mít mnoho atributů:

<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: Atribut Name je ID pro Rule. Musí být jedinečný mezi všemi soubory XML stránky vlastností pro projekt.

• PageTemplate: Hodnotu tohoto atributu používá uživatelské rozhraní k výběru z kolekce šablon uživatelského rozhraní. Šablona "nástroj" vykreslí vlastnosti ve standardním formátu mřížky. Další předdefinované hodnoty pro tento atribut jsou "ladicí program" a "generic". Pokud chcete zobrazit formát uživatelského rozhraní, který je výsledkem zadání těchto hodnot, podívejte se na uzel Ladění a obecný uzel. Uživatelské rozhraní pro šablonu stránky "ladicí program" používá rozevírací pole k přepínání mezi vlastnostmi různých ladicího programu. Šablona "generic" zobrazuje různé kategorie vlastností na jedné stránce, na rozdíl od toho, aby pod uzlem bylo více dílčích Rule uzlů kategorií. Tento atribut je jen návrh uživatelského rozhraní. Soubor XML je navržený tak, aby byl nezávislý na uživatelském rozhraní. Tento atribut může používat jiné uživatelské rozhraní pro různé účely.

• SwitchPrefix: Předpona použitá v příkazovém řádku pro přepínače. Hodnota "/" by byla výsledkem přepínačů, které vypadají jako /ZI, /nologo/W3, atd.

• Order: Návrh potenciálního klienta uživatelského rozhraní v relativním umístění v Rule porovnání se všemi ostatními pravidly v systému.

• xmlns: Standardní element XML. Zobrazí se tři uvedené obory názvů. Tyto atributy odpovídají oborům názvů pro třídy deserializace XML, schématu XML a systémového oboru názvů.

• DisplayName: Název zobrazený v uživatelském rozhraní Rule stránky vlastností uzlu. Tato hodnota je lokalizovaná. Vytvořili DisplayName jsme jako podřízený prvek Rule , nikoli jako atribut (například Name nebo SwitchPrefix) kvůli požadavkům interního lokalizačního nástroje. Z pohledu XML jsou oba ekvivalentní. Můžete ho tedy jednoduše nastavit jako atribut, abyste snížili nepotřebné informace nebo ho nechali tak, jak je.

• DataSource: Tato důležitá vlastnost říká systému projektu umístění ke čtení a zápisu hodnoty vlastnosti a jeho seskupení (vysvětleno později). Pro cl.xmltyto hodnoty jsou:

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

  • Persistence="ProjectFile" říká systému projektu, že všechny vlastnosti by Rule měly být zapsány do souboru projektu nebo souboru seznamu vlastností (v závislosti na tom, který uzel byl použit k vytvoření stránek vlastností). Druhá možná hodnota je "UserFile", která zapíše hodnotu do .user souboru.

  • ItemType="ClCompile" říká, že vlastnosti budou uloženy jako metadata ItemDefinition nebo metadata položky (druhá pouze v případě, že stránky vlastností byly vytvářeny z uzlu souboru v Průzkumníku řešení) tohoto typu položky. Pokud toto pole není nastaveno, vlastnost je zapsána jako společná vlastnost v PropertyGroup.

  • Label="" označuje, že když jsou vlastnosti zapsány jako ItemDefinition metadata, popisek nadřazené ItemDefinitionGroup bude prázdný (každý prvek MSBuild může mít Popisek). Visual Studio 2017 a novější používají skupiny označené popisky k navigaci v souboru projektu .vcxproj. Skupiny, které obsahují většinu Rule vlastností, mají prázdný řetězec jako popisek.

  • HasConfigurationCondition="true" říká systému projektu, aby k hodnotě připevnit podmínku konfigurace, aby se projevila pouze pro aktuální konfiguraci projektu (podmínka může být připojena k nadřazené skupině nebo samotné hodnotě). Otevřete například stránky vlastností mimo uzel projektu a nastavte hodnotu vlastnosti Treat Warnings As Error v části Vlastnosti > konfigurace C/C++ Obecné na Ano. Následující hodnota se zapíše do souboru projektu. Všimněte si podmínky konfigurace připojené k nadřazené ItemDefinitionGroup.

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

    Pokud je tato hodnota nastavena na stránce vlastností pro určitý soubor, například stdafx.cpp, hodnota vlastnosti by měla být zapsána pod stdafx.cpp položkou v souboru projektu, jak je znázorněno zde. Všimněte si, jak je podmínka konfigurace přímo připojená k samotnému metadatu:

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

  Dalším atributem, který DataSource zde není uveden, je PersistedName. Tento atribut můžete použít k reprezentaci vlastnosti v souboru projektu pomocí jiného názvu. Ve výchozím nastavení je tento atribut nastaven na vlastnost Name.

  Jednotlivá vlastnost může přepsat DataSource nadřazenou Rulevlastnost . V takovém případě se umístění pro hodnotu této vlastnosti bude lišit od ostatních vlastností v objektu Rule.

• Existují další atributy Rule, včetně Description a SupportsFileBatching, které zde nejsou zobrazeny. Úplnou sadu atributů použitelných pro určitý Rule nebo jiný prvek lze získat procházením dokumentace pro tyto typy. Případně můžete prozkoumat veřejné vlastnosti typů v Microsoft.Build.Framework.XamlTypes oboru názvů v Microsoft.Build.Framework.dll sestavení.

• DisplayName, PageTemplatea Order jsou vlastnosti související s uživatelským rozhraním, které jsou přítomné v tomto jinak nezávislém datovém modelu uživatelského rozhraní. Tyto vlastnosti jsou téměř jisté, že je používá jakékoli uživatelské rozhraní, které se používá k zobrazení stránek vlastností. DisplayName a Description jsou dvě vlastnosti, které jsou přítomné na téměř všech prvech v souboru XML. A tyto dvě vlastnosti jsou jediné, které jsou lokalizovány.

Prvky kategorií

A Rule může mít více Category prvků. Pořadí, ve kterém jsou kategorie uvedeny v souboru XML, je návrh na uživatelské rozhraní k zobrazení kategorií ve stejném pořadí. Například pořadí kategorií v uzlu C/C++ , který vidíte v uživatelském rozhraní, je stejné jako pořadí v cl.xml. Ukázková kategorie vypadá takto:

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

Tento fragment kódu ukazuje atributy NameDisplayName , které byly popsány dříve. Opět existují další atributy Category , které se v příkladu nezobrazují. O nich se můžete dozvědět v dokumentaci nebo prozkoumáním sestavení pomocí ildasm.exe.

Elementy vlastností

Většina souboru pravidla se skládá z Property prvků. Obsahují seznam všech vlastností v objektu .Rule Každá vlastnost může být jedním z pěti možných typů zobrazených v základním rozhraní: BoolProperty, EnumProperty, IntProperty, StringProperty, a StringListProperty. V souboru možná máte jenom několik těchto typů. Vlastnost má řadu atributů, které umožňují, aby bylo podrobně popsáno. Tady je popsáno StringProperty . Zbytek je podobný.

<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>

Většina atributů v fragmentu kódu byla popsána dříve. Nové jsou Subtype, Categorya Switch.

• Subtype je atribut dostupný pouze pro StringProperty prvky a StringListProperty prvky. Poskytuje kontextové informace. Například hodnota file označuje, že vlastnost představuje cestu k souboru. Visual Studio používá tyto kontextové informace k vylepšení prostředí pro úpravy. Může například poskytnout okno Průzkumníka Windows, které uživateli umožňuje vizuálně zvolit soubor jako editor vlastnosti.

• Category: Kategorie, pod kterou tato vlastnost spadá. Zkuste tuto vlastnost najít v kategorii Výstupní soubory v uživatelském rozhraní.

• Switch: Pokud pravidlo představuje nástroj, jako je například nástroj kompilátoru, většina Rule vlastností se předá jako přepínače do spustitelného souboru nástroje v době sestavení. Hodnota tohoto atributu označuje, který literál přepínače použít. Příklad <StringProperty> určuje, že jeho přepínač by měl být Fo. V kombinaci s atributem nadřazeného Ruleobjektu SwitchPrefix se tato vlastnost předává spustitelnému souboru jako /Fo"Debug\". Je viditelný v příkazovém řádku pro C/C++ v uživatelském rozhraní stránky vlastností.

  Mezi další atributy vlastnosti patří:

• Visible: Pokud nechcete, aby se vaše vlastnost zobrazovala na stránkách vlastností, ale chcete, aby byla k dispozici v době sestavení, nastavte tento atribut na falsehodnotu .

• ReadOnly: Chcete-li poskytnout zobrazení hodnoty této vlastnosti jen pro čtení na stránkách vlastností, nastavte tento atribut na true.

• IncludeInCommandLine: V době sestavení nemusí nástroj potřebovat některé jeho vlastnosti. Nastavte tento atribut tak, aby false se zabránilo předání konkrétní vlastnosti.