Pliki wskazówki

Plik wskazówek zawiera makra, które w przeciwnym razie spowodowałyby pominięcie regionów kodu przez analizator bazy danych przeglądania języka C++. Po otwarciu projektu programu Visual Studio C++ analizator analizuje kod w każdym pliku źródłowym w projekcie i tworzy bazę danych z informacjami o każdym identyfikatorze. Środowisko IDE używa tych informacji do obsługi funkcji przeglądania kodu, takich jak przeglądarka Widok klas i pasek nawigacyjny.

Analizator bazy danych przeglądania języka C++ to analizator rozmyty, który może analizować duże ilości kodu w krótkim czasie. Jednym z powodów jest to, że pomija zawartość bloków. Na przykład rejestruje tylko lokalizację i parametry funkcji i ignoruje jego zawartość. Niektóre makra mogą powodować problemy dotyczące heurystyki używanej do określania początku i końca bloku. Te problemy powodują nieprawidłowe rejestrowanie regionów kodu.

Pominięte regiony mogą manifestować się na wiele sposobów:

• Brakujące typy i funkcje w widoku klasy, przejdź do i pasek nawigacyjny

• Nieprawidłowe zakresy na pasku nawigacyjnym

• Sugestie dotyczące tworzenia deklaracji/definicji dla funkcji, które są już zdefiniowane

Plik wskazówek zawiera wskazówki umożliwiające dostosowanie użytkownika, które mają taką samą składnię jak definicje makr języka C/C++. Język Visual C++ zawiera wbudowany plik wskazówek, który jest wystarczający dla większości projektów. Można jednak utworzyć własne pliki wskazówek, aby ulepszyć analizator specjalnie dla projektu.

Ważne

W przypadku modyfikowania lub dodawania pliku wskazówek należy wykonać dodatkowe kroki, aby zmiany zaczęły obowiązywać:

• W wersjach wcześniejszych niż Program Visual Studio 2017 w wersji 15.6: Usuń plik sdf i/lub VC.db w rozwiązaniu dla wszystkich zmian.
• W programie Visual Studio 2017 w wersji 15.6 lub nowszej: Zamknij i otwórz ponownie rozwiązanie po dodaniu nowych plików wskazówek.

Scenariusz

#define NOEXCEPT noexcept
void Function() NOEXCEPT
{
}

Bez pliku Function wskazówek nie jest wyświetlany w widoku klasy, przejdź do ani na pasku nawigacyjnym. Po dodaniu pliku wskazówek z tą definicją makra analizator rozumie i zastępuje NOEXCEPT makro, co umożliwia poprawne analizowanie funkcji:

#define NOEXCEPT

Makra zakłócające

Istnieją dwie kategorie makr, które zakłócają analizator:

• Makra hermetyzujące słowa kluczowe, które zdobią funkcję

  #define NOEXCEPT noexcept
  #define STDMETHODCALLTYPE __stdcall
  

  W przypadku tych typów makr w pliku wskazówek wymagana jest tylko nazwa makra:

  #define NOEXCEPT
  #define STDMETHODCALLTYPE
  

• Makra zawierające nawiasy niezrównoważone

  #define BEGIN {
  

  W przypadku tych typów makr w pliku wskazówek wymagana jest zarówno nazwa makra, jak i jego zawartość:

  #define BEGIN {
  

Obsługa edytora

Począwszy od programu Visual Studio 2017 w wersji 15.8 istnieje kilka funkcji umożliwiających identyfikowanie makr zakłócających działanie:

• Makra, które znajdują się wewnątrz regionów pomijanych przez analizator, są wyróżnione.

• Istnieje szybka akcja umożliwiająca utworzenie pliku wskazówek zawierającego wyróżnione makro lub jeśli istnieje istniejący plik wskazówek, aby dodać makro do pliku wskazówek.

Po wykonaniu jednej z szybkich akcji analizator ponownie analizuje pliki, których dotyczy plik wskazówek.

Domyślnie makro problemu jest wyróżnione jako sugestia. Wyróżnienie można zmienić na bardziej zauważalne, takie jak czerwony lub zielony wywiórz. Użyj opcji Makra w pominiętych regionach przeglądania w sekcji Zygzaki kodu w obszarze Narzędzia>Opcje>Edytor>tekstu C/C++>View.

Wyświetlanie błędów bazy danych przeglądania

Polecenie menu Wyświetlanie bazy danych przeglądania projektu>wyświetla wszystkie regiony, w których nie można przeanalizować na liście błędów. Polecenie ma usprawnić tworzenie początkowego pliku wskazówek. Jednak analizator nie może stwierdzić, czy przyczyną błędu było makro zakłócające, więc należy ocenić każdy błąd. Uruchom polecenie Wyświetlanie błędów bazy danych przeglądania i przejdź do każdego błędu, aby załadować plik, którego dotyczy problem w edytorze. Po załadowaniu pliku, jeśli jakiekolwiek makra znajdują się w regionie, zostaną one wyróżnione. Możesz wywołać szybkie akcje, aby dodać je do pliku wskazówek. Po zaktualizowaniu pliku wskazówek lista błędów zostanie automatycznie zaktualizowana. Alternatywnie, jeśli ręcznie modyfikujesz plik wskazówek, możesz użyć polecenia Ponowne skanowanie rozwiązania w celu wyzwolenia aktualizacji.

Architektura

Pliki wskazówek odnoszą się do katalogów fizycznych, a nie katalogów logicznych pokazanych w Eksplorator rozwiązań. Nie musisz dodawać pliku wskazówek do projektu, aby plik wskazówek miał wpływ. System analizowania używa plików wskazówek tylko wtedy, gdy analizuje pliki źródłowe.

Każdy plik wskazówek ma nazwę cpp.hint. Wiele katalogów może zawierać plik wskazówek, ale w określonym katalogu może wystąpić tylko jeden plik wskazówek.

Na projekt może mieć wpływ zero lub więcej plików wskazówek. Jeśli nie ma plików wskazówek, system analizowania używa technik odzyskiwania błędów do ignorowania niezdecydowalnego kodu źródłowego. W przeciwnym razie system analizowania używa następującej strategii do znajdowania i zbierania wskazówek.

Kolejność wyszukiwania

Analizowanie katalogów wyszukiwania plików wskazówek w następującej kolejności.

• Katalog zawierający pakiet instalacyjny programu Visual C++ (vcpackages). Ten katalog zawiera wbudowany plik wskazówek, który opisuje symbole w często używanych plikach systemowych, takich jak windows.h. W związku z tym projekt automatycznie dziedziczy większość wskazówek, których potrzebuje.

• Ścieżka z katalogu głównego pliku źródłowego do katalogu zawierającego sam plik źródłowy. W typowym projekcie programu Visual Studio C++ katalog główny zawiera plik rozwiązania lub projektu.

  Wyjątkiem od tej reguły jest, jeśli plik zatrzymania znajduje się w ścieżce do pliku źródłowego. Plik zatrzymania to dowolny plik o nazwie cpp.stop. Plik zatrzymania zapewnia dodatkową kontrolę nad kolejnością wyszukiwania. Zamiast rozpoczynać się od katalogu głównego, analizowanie wyszukiwania systemu z katalogu zawierającego plik zatrzymania do katalogu zawierającego plik źródłowy. W typowym projekcie nie potrzebujesz pliku zatrzymania.

Zbieranie wskazówek

Plik wskazówek zawiera zero lub więcej wskazówek. Wskazówka jest definiowana lub usuwana tak samo jak makro C/C++. Oznacza to, że #define dyrektywa preprocesora tworzy lub ponownie definiuje wskazówkę, a #undef dyrektywa usuwa wskazówkę.

System analizowania otwiera każdy plik wskazówek w kolejności wyszukiwania opisanej wcześniej. Gromadzi on wskazówki każdego pliku w zestawie skutecznych wskazówek, a następnie używa skutecznych wskazówek do interpretacji identyfikatorów w kodzie.

System analizowania używa tych reguł do gromadzenia wskazówek:

• Jeśli nowa wskazówka określa nazwę, która nie jest jeszcze zdefiniowana, nowa wskazówka dodaje nazwę do obowiązujących wskazówek.

• Jeśli nowa wskazówka określa nazwę, która jest już zdefiniowana, nowa wskazówka ponownie definiuje istniejącą wskazówkę.

• Jeśli nowa wskazówka jest dyrektywą #undef określającą istniejącą efektywną wskazówkę, nowa wskazówka usuwa istniejącą wskazówkę.

Pierwsza reguła oznacza, że skuteczne wskazówki są dziedziczone z wcześniej otwartych plików wskazówek. Dwie ostatnie reguły oznaczają, że wskazówki w dalszej części kolejności wyszukiwania mogą zastąpić wcześniejsze wskazówki. Można na przykład zastąpić wszystkie poprzednie wskazówki, jeśli utworzysz plik wskazówek w katalogu zawierającym plik źródłowy.

Aby zapoznać się z opisem sposobu zbierania wskazówek, zobacz sekcję Przykład .

Składnia

Wskazówki można tworzyć i usuwać przy użyciu tej samej składni co dyrektywy preprocesora w celu tworzenia i usuwania makr. W rzeczywistości system analizy używa preprocesora C/C++ do oceny wskazówek. Aby uzyskać więcej informacji na temat dyrektyw preprocesora, zobacz #define Dyrektywy (C/C++) i dyrektywy #undef (C/C++).

Jedynymi nietypowymi elementami składni są @<ciągi zastępcze , @=i @> . Te ciągi zastępcze specyficzne dla pliku wskazówek są używane tylko w makrach mapy . Mapa to zestaw makr, które wiążą dane, funkcje lub zdarzenia z innymi danymi, funkcjami lub procedurami obsługi zdarzeń. Na przykład MFC używa map do tworzenia map komunikatów i ATL używa map do tworzenia map obiektów. Ciągi zastępcze specyficzne dla pliku wskazówek oznaczają elementy początkowe, pośrednie i końcowe mapy. Znacząca jest tylko nazwa makra mapy. W związku z tym każdy ciąg zastępczy celowo ukrywa implementację makra.

Wskazówki używają tej składni:

Składnia	Znaczenie
#defineciąg zastępczy nazwywskazówki #defineparametr hint-name(, ...)ciąg zastępczy	Dyrektywa preprocesora, która definiuje nową wskazówkę lub ponownie definiuje istniejącą wskazówkę. Po dyrektywie preprocesor zastępuje każde wystąpienie nazwy wskazówki w kodzie źródłowym ciągiem zastępczym. Drugi formularz składni definiuje wskazówkę przypominającą funkcję. Jeśli wskazówka przypominająca funkcję występuje w kodzie źródłowym, preprocesor najpierw zastępuje każde wystąpienie parametru w ciągu zastępczym odpowiednim argumentem w kodzie źródłowym, a następnie zastępuje wartość hint-name ciągiem zastępczym.
@<	Ciąg zastępczy specyficzny dla pliku wskazówek, który wskazuje początek zestawu elementów mapy.
@=	Ciąg zastępczy specyficzny dla pliku wskazówek, który wskazuje element mapy pośredniej. Mapa może zawierać wiele elementów mapy.
@>	Ciąg zastępczy specyficzny dla pliku wskazówek, który wskazuje koniec zestawu elementów mapy.
#undefnazwa-wskazówki	Dyrektywa preprocesora, która usuwa istniejącą wskazówkę. Nazwa wskazówki jest dostarczana przez identyfikator nazwy wskazówki.
//Komentarz	Komentarz jednowierszowy.
/*Komentarz*/	Komentarz wielowierszowy.

Przykład

W tym przykładzie pokazano, jak wskazówki są zbierane z plików wskazówek. W tym przykładzie nie są używane pliki zatrzymane.

Ilustracja przedstawia niektóre katalogi fizyczne w projekcie Visual Studio C++. Istnieją pliki wskazówek w katalogach vcpackages, Debug, A1i A2 .

Katalogi plików wskazówek

Katalogi i zawartość pliku wskazówek

Ta lista zawiera katalogi w tym projekcie zawierające pliki wskazówek oraz zawartość tych plików wskazówek. Na liście znajduje się tylko kilka wskazówek w vcpackages pliku wskazówek katalogu:

• pakiety vcpackage

  // vcpackages (partial list)
  #define _In_
  #define _In_opt_
  #define _In_z_
  #define _In_opt_z_
  #define _In_count_(size)
  

• Debugowanie

  // Debug
  #undef _In_
  #define OBRACE {
  #define CBRACE }
  #define RAISE_EXCEPTION(x) throw (x)
  #define START_NAMESPACE namespace MyProject {
  #define END_NAMESPACE }
  

• A1

  // A1
  #define START_NAMESPACE namespace A1Namespace {
  

• A2

  // A2
  #undef OBRACE
  #undef CBRACE
  

Skuteczne wskazówki

W tej tabeli wymieniono obowiązujące wskazówki dotyczące plików źródłowych w tym projekcie:

• Plik źródłowy: A1_A2_B.cpp

• Skuteczne wskazówki:

  // vcpackages (partial list)
  #define _In_opt_
  #define _In_z_
  #define _In_opt_z_
  #define _In_count_(size)
  // Debug...
  #define RAISE_EXCEPTION(x) throw (x)
  // A1
  #define START_NAMESPACE namespace A1Namespace {
  // ...Debug
  #define END_NAMESPACE }
  

Te uwagi dotyczą powyższej listy:

• Skuteczne wskazówki pochodzą z vcpackageskatalogów , Debug, A1i A2 .

• Dyrektywa #undef w Debug pliku wskazówek usunęła #define _In_ wskazówkę w vcpackages pliku wskazówek katalogu.

• Plik wskazówek w A1 katalogu ponownie definiuje element START_NAMESPACE.

• Wskazówka #undef w A2 katalogu usunęła wskazówki dotyczące OBRACE elementów i CBRACE w Debug pliku wskazówek katalogu.

Zobacz też

Typy plików utworzone dla projektów Visual Studio C++
#define, dyrektywa (C/C++)
#undef, dyrektywa (C/C++)
Adnotacje SAL