Instrukcje: tworzenie, inicjowanie i konfigurowanie przełączników śledzenia

Uwaga

Ten artykuł jest specyficzny dla programu .NET Framework. Nie ma zastosowania do nowszych implementacji platformy .NET, w tym .NET 6 i nowszych wersji.

Przełączniki śledzenia umożliwiają włączanie, wyłączanie i filtrowanie danych wyjściowych śledzenia.

Tworzenie i inicjowanie przełącznika śledzenia

Aby można było używać przełączników śledzenia, należy je najpierw utworzyć i umieścić w kodzie. Istnieją dwie wstępnie zdefiniowane klasy, z których można tworzyć obiekty przełącznika: klasę System.Diagnostics.BooleanSwitch i klasę System.Diagnostics.TraceSwitch . BooleanSwitch Jeśli zależy Ci tylko na tym, czy pojawia się komunikat śledzenia, należy użyć TraceSwitch polecenia , jeśli chcesz dyskryminować poziomy śledzenia. Jeśli używasz elementu TraceSwitch, możesz zdefiniować własne komunikaty debugowania i skojarzyć je z różnymi poziomami śledzenia. Oba typy przełączników można używać z funkcją śledzenia lub debugowania. Domyślnie parametr BooleanSwitch jest wyłączony, a parametr TraceSwitch jest ustawiony na poziom TraceLevel.Off. Przełączniki śledzenia można tworzyć i umieszczać w dowolnej części kodu, która może ich używać.

Mimo że można ustawić poziomy śledzenia i inne opcje konfiguracji w kodzie, zalecamy użycie pliku konfiguracji do zarządzania stanem przełączników. Dzieje się tak, ponieważ zarządzanie konfiguracją przełączników w systemie konfiguracji zapewnia większą elastyczność — można włączać i wyłączać różne przełączniki i zmieniać poziomy bez ponownego komplikowania aplikacji.

Aby utworzyć i zainicjować przełącznik śledzenia

1. Zdefiniuj przełącznik jako typ lub typ System.Diagnostics.BooleanSwitchSystem.Diagnostics.TraceSwitch i ustaw nazwę i opis przełącznika.

2. Skonfiguruj przełącznik śledzenia. Aby uzyskać więcej informacji, zobacz Konfigurowanie przełączników śledzenia.

   Poniższy kod tworzy dwa przełączniki— jeden z każdego typu:

   Dim dataSwitch As New BooleanSwitch("Data", "DataAccess module")
   Dim generalSwitch As New TraceSwitch("General", "Entire application")
   

   System.Diagnostics.BooleanSwitch dataSwitch =
      new System.Diagnostics.BooleanSwitch("Data", "DataAccess module");
   System.Diagnostics.TraceSwitch generalSwitch =
      new System.Diagnostics.TraceSwitch("General",
      "Entire application");
   

Konfigurowanie przełączników śledzenia

Po rozproszeniu aplikacji można nadal włączać lub wyłączać dane wyjściowe śledzenia, konfigurując przełączniki śledzenia w aplikacji. Skonfigurowanie przełącznika oznacza zmianę jego wartości ze źródła zewnętrznego po jego zainicjowaniu. Wartości obiektów przełącznika można zmienić przy użyciu pliku konfiguracji. Należy skonfigurować przełącznik śledzenia, aby włączyć i wyłączyć lub ustawić jego poziom, określając ilość i typ komunikatów, które przekazuje do odbiorników.

Przełączniki są konfigurowane przy użyciu pliku config. W przypadku aplikacji sieci Web jest to plik Web.config skojarzony z projektem. W aplikacji systemu Windows ten plik ma nazwę (nazwa aplikacji).exe.config. W wdrożonej aplikacji ten plik musi znajdować się w tym samym folderze co plik wykonywalny.

Gdy aplikacja wykonuje kod, który tworzy wystąpienie przełącznika po raz pierwszy, sprawdza plik konfiguracji pod kątem informacji na poziomie śledzenia o nazwanym przełączniku. System śledzenia sprawdza plik konfiguracji tylko raz dla dowolnego określonego przełącznika — przy pierwszym utworzeniu przełącznika przez aplikację.

W wdrożonej aplikacji można włączyć kod śledzenia, konfigurując ponownie obiekty przełącznika, gdy aplikacja nie jest uruchomiona. Zazwyczaj obejmuje to włączenie i wyłączenie obiektów przełącznika lub zmianę poziomów śledzenia, a następnie ponowne uruchomienie aplikacji.

Podczas tworzenia wystąpienia przełącznika można go również zainicjować, określając dwa argumenty: argument displayName i argument opisu . Argument displayName konstruktora ustawia Switch.DisplayName właściwość Switch wystąpienia klasy. DisplayName to nazwa używana do konfigurowania przełącznika w pliku config, a argument opisu powinien zwrócić krótki opis przełącznika i komunikaty, które kontroluje.

Oprócz określenia nazwy przełącznika do skonfigurowania należy również określić wartość przełącznika. Ta wartość jest liczbą całkowitą. W przypadku BooleanSwitchparametru wartość 0 odpowiada wartości Wyłączone, a każda wartość niezerowa odpowiada wartości Włączone. W przypadku TraceSwitchwartości , odpowiednio 0,1,2,3 i 4 odpowiadają wartościom Off, Error, Warning, Info i Verbose. Dowolna liczba większa niż 4 jest traktowana jako Pełne, a dowolna liczba mniejsza niż zero jest traktowana jako Wyłączona.

Uwaga

W programie .NET Framework w wersji 2.0 można użyć tekstu, aby określić wartość przełącznika. Na przykład dla elementu BooleanSwitch lub tekst reprezentujący wartość wyliczenia, true taką jak Error dla elementu TraceSwitch. Wiersz <add name="myTraceSwitch" value="Error" /> jest odpowiednikiem <add name="myTraceSwitch" value="1" />.

Aby użytkownicy końcowi mogli skonfigurować przełączniki śledzenia aplikacji, należy podać szczegółową dokumentację dotyczącą przełączników w aplikacji. Należy szczegółowo określić, które przełączniki kontrolują, co i jak je włączać i wyłączać. Należy również podać użytkownikowi końcowemu plik config, który ma odpowiednią pomoc w komentarzach.

Aby skonfigurować przełączniki śledzenia

1. Aby można było używać przełączników śledzenia, należy je najpierw utworzyć i umieścić w kodzie zgodnie z opisem w sekcji Tworzenie i inicjowanie przełącznika śledzenia.

2. Jeśli projekt nie zawiera pliku konfiguracji (app.config lub Web.config), z menu Project wybierz pozycję Dodaj nowy element.

   • Visual Basic: w oknie dialogowym Dodawanie nowego elementu wybierz pozycję Plik konfiguracji aplikacji.

     Plik konfiguracji aplikacji jest tworzony i otwierany. Jest to dokument XML, którego elementem głównym jest <configuration>.

   • Visual C#: W oknie dialogowym Dodawanie nowego elementu wybierz pozycję Plik XML. Nadaj temu plikowi nazwę app.config. W edytorze XML po deklaracji XML dodaj następujący kod XML:

     <configuration>
     </configuration>
     

     Po skompilowaniu projektu plik app.config jest kopiowany do folderu wyjściowego projektu i ma nazwę applicationname.exe.config.

3. Po tagu <configuration> , ale przed tagiem </configuration> dodaj odpowiedni kod XML, aby skonfigurować przełączniki. W poniższych przykładach pokazano element BooleanSwitch z właściwością DataMessageSwitchDisplayName i TraceSwitch z właściwością TraceLevelSwitchDisplayName klasy .

   <system.diagnostics>
      <switches>
         <add name="DataMessagesSwitch" value="0" />
         <add name="TraceLevelSwitch" value="0" />
      </switches>
   </system.diagnostics>
   

   W tej konfiguracji oba przełączniki są wyłączone.

4. Jeśli musisz włączyć przełącznik logiczny, taki jak DataMessagesSwitch pokazano w poprzednim przykładzie, zmień wartość na dowolną liczbę całkowitą inną niż 0.

5. Jeśli musisz włączyć przełącznik TraceSwitch, taki jak TraceLevelSwitch pokazano w poprzednim przykładzie, zmień wartość na odpowiednie ustawienie poziomu (od 1 do 4).

6. Dodaj komentarze do pliku .config, aby użytkownik końcowy zrozumiał, jakie wartości należy zmienić, aby odpowiednio skonfigurować przełączniki.

   W poniższym przykładzie pokazano, jak może wyglądać końcowy kod, w tym komentarze:

   <system.diagnostics>
      <switches>
         <!-- This switch controls data messages. In order to receive data
            trace messages, change value="0" to value="1" -->
         <add name="DataMessagesSwitch" value="0" />
         <!-- This switch controls general messages. In order to
            receive general trace messages change the value to the
            appropriate level. "1" gives error messages, "2" gives errors
            and warnings, "3" gives more detailed error information, and
            "4" gives verbose trace information -->
         <add name="TraceLevelSwitch" value="0" />
      </switches>
   </system.diagnostics>
   

Zobacz też

• Śledzenie i instrumentowanie aplikacji
• Instrukcje: Dodawanie instrukcji śledzenia do kodu aplikacji
• Przełączniki śledzenia
• Schemat ustawień śledzenia i debugowania