Pliki reguł XML strony właściwości

Strony właściwości projektu w środowisku IDE są konfigurowane przez pliki XML w domyślnym folderze reguł. Pliki XML opisują nazwy reguł, kategorii i poszczególnych właściwości, ich typ danych, wartości domyślne i sposób ich wyświetlania. Po ustawieniu właściwości w środowisku IDE nowa wartość jest przechowywana w pliku projektu.

Ścieżka do folderu reguł domyślnych zależy od ustawień regionalnych i używanej wersji programu Visual Studio. W wierszu polecenia programu Visual Studio 2019 lub nowszego dewelopera folder reguł to %VSINSTALLDIR%MSBuild\Microsoft\VC\<version>\<locale>\, gdzie <version> wartość znajduje v160 się w programie Visual Studio 2019. Jest <locale> to identyfikator LCID, na przykład 1033 dla języka angielskiego. W programie Visual Studio 2017 folder reguł to %VSINSTALLDIR%Common7\IDE\VC\VCTargets\<locale>\. W wierszu polecenia programu Visual Studio 2015 lub starszego dewelopera folder reguł to %ProgramFiles(x86)%\MSBuild\Microsoft.Cpp\v4.0\<version>\<locale>\. Użyjesz innej ścieżki dla każdej zainstalowanej wersji programu Visual Studio i dla każdego języka. Na przykład domyślną ścieżką folderu reguł programu Visual Studio 2019 Community Edition w języku angielskim może być C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\MSBuild\Microsoft\VC\v160\1033\.

Wystarczy zrozumieć wewnętrzne działania tych plików i środowiska IDE programu Visual Studio w kilku scenariuszach:

• Chcesz utworzyć stronę właściwości niestandardowej lub
• Chcesz dostosować właściwości projektu bez użycia środowiska IDE programu Visual Studio.

Zawartość plików reguł

Najpierw otwórzmy strony właściwości projektu. Kliknij prawym przyciskiem myszy węzeł projektu w Eksplorator rozwiązań i wybierz polecenie Właściwości:

Każdy węzeł w obszarze Właściwości konfiguracji jest nazywany regułą. Reguła czasami reprezentuje jedno narzędzie, takie jak kompilator. Ogólnie rzecz biorąc, termin odnosi się do czegoś, co ma właściwości, które wykonuje i które może wygenerować niektóre dane wyjściowe. Każda reguła jest wypełniana z pliku XML w folderze reguł domyślnych. Na przykład reguła języka C/C++, która jest tutaj wyświetlana, jest wypełniana przez cl.xmlelement .

Każda reguła ma zestaw właściwości, które są zorganizowane w kategorie. Każdy węzeł podrzędny w ramach reguły reprezentuje kategorię. Na przykład węzeł Optymalizacji w obszarze C/C++ zawiera wszystkie właściwości związane z optymalizacją narzędzia kompilatora. Właściwości i ich wartości są renderowane w formacie siatki w okienku po prawej stronie.

Możesz otworzyć cl.xml w Notatniku lub dowolnym edytorze XML. Zobaczysz węzeł główny o nazwie Rule. Definiuje tę samą listę właściwości, które są wyświetlane w interfejsie użytkownika wraz z dodatkowymi metadanymi.

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

Istnieje jeden plik XML dla każdego węzła w obszarze Właściwości konfiguracji w interfejsie użytkownika stron właściwości. Reguły można dodawać lub usuwać w interfejsie użytkownika: można to zrobić, dołączając lub usuwając lokalizacje do odpowiednich plików XML w projekcie. Na przykład sposób Microsoft.CppBuild.targets (znaleziono jeden poziom wyższy niż folder 1033) obejmuje następujące elementy cl.xml:

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

Jeśli usuwasz cl.xml wszystkie dane, masz następującą podstawową strukturę:

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

W następnej sekcji opisano każdy element główny i niektóre metadane, które można dołączyć.

Atrybuty reguły

Element <Rule> to węzeł główny w pliku XML. Może mieć wiele atrybutów:

<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: Atrybut Name jest identyfikatorem Rule. Musi być unikatowy wśród wszystkich plików XML strony właściwości dla projektu.

• PageTemplate: Wartość tego atrybutu jest używana przez interfejs użytkownika do wyboru z kolekcji szablonów interfejsu użytkownika. Szablon "tool" renderuje właściwości w standardowym formacie siatki. Inne wbudowane wartości tego atrybutu to "debuger" i "generic". Zobacz odpowiednio węzeł Debugowanie i węzeł Ogólny, aby wyświetlić format interfejsu użytkownika wynikający z określenia tych wartości. Interfejs użytkownika dla szablonu strony "debugera" używa pola rozwijanego, aby przełączać się między właściwościami różnych debugerów. Szablon "ogólny" wyświetla różne kategorie właściwości na jednej stronie, w przeciwieństwie do wielu węzłów podrzędnych kategorii w węźle Rule . Ten atrybut jest tylko sugestią interfejsu użytkownika. Plik XML został zaprojektowany tak, aby był niezależny od interfejsu użytkownika. Inny interfejs użytkownika może używać tego atrybutu do różnych celów.

• SwitchPrefix: prefiks używany w wierszu polecenia dla przełączników. Wartość parametru "/" spowoduje przełączenia, które wyglądają jak /ZI, /nologo, /W3i tak dalej.

• Order: sugestia potencjalnego klienta interfejsu użytkownika w względnej lokalizacji w Rule porównaniu do wszystkich innych reguł w systemie.

• xmlns: standardowy element XML. Widoczne są trzy przestrzenie nazw. Te atrybuty odpowiadają przestrzeniom nazw odpowiednio klas deserializacji XML, schematowi XML i przestrzeni nazw systemu.

• DisplayName: nazwa wyświetlana w interfejsie użytkownika strony właściwości dla węzła Rule . Ta wartość jest zlokalizowana. Utworzyliśmy DisplayName jako element Rule podrzędny zamiast atrybutu (na przykład Name lub SwitchPrefix) z powodu wymagań wewnętrznych narzędzi lokalizacji. Z perspektywy XML oba są równoważne. Możesz więc po prostu uczynić go atrybutem, aby zmniejszyć bałagan lub pozostawić go tak, jak to jest.

• DataSource: Ta ważna właściwość informuje system projektu o lokalizacji odczytu i zapisu wartości właściwości oraz jej grupowaniu (wyjaśnione później). W przypadku cl.xmlelementu następujące wartości to:

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

  • Persistence="ProjectFile" informuje system projektu, że wszystkie właściwości obiektu Rule powinny być zapisywane w pliku projektu lub w pliku arkusza właściwości (w zależności od tego, który węzeł został użyty do zduplikowania stron właściwości). Inną możliwą wartością jest "UserFile", która zapisze wartość w .user pliku.

  • ItemType="ClCompile" mówi, że właściwości będą przechowywane jako metadane elementu ItemDefinition lub metadane elementu (te ostatnie tylko wtedy, gdy strony właściwości zostały zduplikowane z węzła pliku w Eksploratorze rozwiązań) tego typu elementu. Jeśli to pole nie jest ustawione, właściwość jest zapisywana jako wspólna właściwość w właściwości PropertyGroup.

  • Label="" wskazuje, że gdy właściwości są zapisywane jako ItemDefinition metadane, etykieta nadrzędnego elementu ItemDefinitionGroup będzie pusta (każdy element MSBuild może mieć etykietę). Program Visual Studio 2017 lub nowszy użyj grup oznaczonych etykietami, aby przejść do pliku projektu .vcxproj. Grupy zawierające większość Rule właściwości mają pusty ciąg jako etykietę.

  • HasConfigurationCondition="true" informuje system projektu, aby umieścić warunek konfiguracji do wartości, tak aby obowiązywał tylko dla bieżącej konfiguracji projektu (warunek może zostać umieszczony w grupie nadrzędnej lub samej wartości). Na przykład otwórz strony właściwości w węźle projektu i ustaw wartość właściwości Traktuj ostrzeżenia jako błąd w obszarze Właściwości > konfiguracji C/C++ Ogólne na "Tak". Następująca wartość jest zapisywana w pliku projektu. Zwróć uwagę na warunek konfiguracji dołączony do nadrzędnej grupy ItemDefinitionGroup.

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

    Jeśli ta wartość jest ustawiona na stronie właściwości dla określonego pliku, takiego jak stdafx.cpp, wartość właściwości powinna zostać zapisana w stdafx.cpp elemencie w pliku projektu, jak pokazano tutaj. Zwróć uwagę, że warunek konfiguracji jest bezpośrednio dołączony do samych metadanych:

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

  Innym atrybutem, który DataSource nie ma na liście, jest PersistedName. Tego atrybutu można użyć do reprezentowania właściwości w pliku projektu przy użyciu innej nazwy. Domyślnie ten atrybut jest ustawiony na właściwość Name.

  Właściwość indywidualna może zastąpić DataSource element elementu nadrzędnego Rule. W takim przypadku lokalizacja wartości tej właściwości będzie inna niż inne właściwości w obiekcie Rule.

• Istnieją inne atrybuty Ruleelementu , w tym Description i SupportsFileBatching, które nie są tutaj wyświetlane. Pełny zestaw atrybutów mających zastosowanie do elementu Rule lub innego elementu można uzyskać, przeglądając dokumentację dla tych typów. Alternatywnie można sprawdzić właściwości publiczne typów w Microsoft.Build.Framework.XamlTypes przestrzeni nazw w Microsoft.Build.Framework.dll zestawie.

• DisplayName, PageTemplatei Order są właściwościami powiązanymi z interfejsem użytkownika, które są obecne w tym modelu danych niezależnych od interfejsu użytkownika. Te właściwości są prawie pewne do użycia przez dowolny interfejs użytkownika używany do wyświetlania stron właściwości. DisplayName i Description to dwie właściwości, które znajdują się w prawie wszystkich elementach w pliku XML. Te dwie właściwości są jedynymi, które są zlokalizowane.

Elementy kategorii

Element Rule może zawierać wiele Category elementów. Kolejność, w której kategorie są wymienione w pliku XML, to sugestia interfejsu użytkownika w celu wyświetlenia kategorii w tej samej kolejności. Na przykład kolejność kategorii w węźle C/C++ widocznym w interfejsie użytkownika jest taka sama jak kolejność w pliku cl.xml. Przykładowa kategoria wygląda następująco:

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

Ten fragment kodu przedstawia Name atrybuty i DisplayName , które zostały opisane wcześniej. Po raz kolejny istnieją inne atrybuty Category , które mogą mieć, które nie są wyświetlane w przykładzie. Możesz je dowiedzieć się, czytając dokumentację lub sprawdzając zestawy przy użyciu polecenia ildasm.exe.

Elementy właściwości

Większość pliku reguły składa się z Property elementów. Zawierają one listę wszystkich właściwości w obiekcie Rule. Każda właściwość może być jednym z pięciu możliwych typów pokazanych w podstawowej strukturze: BoolProperty, , IntPropertyEnumProperty, StringPropertyi StringListProperty. W pliku może istnieć tylko kilka z tych typów. Właściwość ma wiele atrybutów, które umożliwiają jej szczegółowe opisanie. Opisano StringProperty to tutaj. Reszta jest podobna.

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

Większość atrybutów we fragmencie kodu została wcześniej opisana. Nowe to Subtype, Categoryi Switch.

• Subtype jest atrybutem dostępnym tylko dla StringProperty elementów i StringListProperty . Udostępnia informacje kontekstowe. Na przykład wartość file wskazuje, że właściwość reprezentuje ścieżkę pliku. Program Visual Studio używa takich informacji kontekstowych, aby ulepszyć środowisko edycji. Może na przykład udostępnić okno Eksploratora Windows, które umożliwia użytkownikowi wizualne wybranie pliku jako edytora właściwości.

• Category: kategoria, w której znajduje się ta właściwość. Spróbuj znaleźć tę właściwość w kategorii Pliki wyjściowe w interfejsie użytkownika.

• Switch: Gdy reguła reprezentuje narzędzie, takie jak narzędzie kompilatora, większość Rule właściwości jest przekazywana jako przełączniki do pliku wykonywalnego narzędzia w czasie kompilacji. Wartość tego atrybutu wskazuje, który literał przełącznika ma być używany. W przykładzie <StringProperty> określono, że jego przełącznik powinien mieć wartość Fo. W połączeniu z atrybutem SwitchPrefix w obiekcie nadrzędnym Ruleta właściwość jest przekazywana do pliku wykonywalnego jako /Fo"Debug\". Jest on widoczny w wierszu polecenia dla języka C/C++ w interfejsie użytkownika strony właściwości.

  Inne atrybuty właściwości to:

• Visible: Jeśli nie chcesz, aby właściwość była wyświetlana na stronach właściwości, ale chcesz, aby była dostępna w czasie kompilacji, ustaw ten atrybut na falsewartość .

• ReadOnly: Jeśli chcesz podać widok wartości tej właściwości tylko do odczytu na stronach właściwości, ustaw ten atrybut na truewartość .

• IncludeInCommandLine: W czasie kompilacji narzędzie może nie potrzebować niektórych jego właściwości. Ustaw ten atrybut, aby false uniemożliwić przekazywanie określonej właściwości.