逐步解說：篩選 My.Application.Log 輸出 (Visual Basic)

發行項
06/10/2015

此逐步解說會示範如何變更篩選 My.Application.Log 物件的預設記錄檔，才能控制從 Log 物件傳送到接聽程式的資訊，以及接聽程式寫入的資訊。因為組態資訊會儲存於應用程式的組態檔中，所以即使已建置應用程式，您還是可以變更記錄的行為。

使用者入門

My.Application.Log 所寫入的每一個訊息都會有相關聯的嚴重性層級，讓篩選機制可以利用它控制記錄輸出。此範例應用程式會使用 My.Application.Log 方法，寫入數個具有不同嚴重性層級的記錄訊息。

若要建置範例應用程式

開啟新的 Visual Basic Windows 應用程式專案。
將名為 Button1 的按鈕加入至 Form1。

在 Button1 的 Click 事件處理常式中，加入下列程式碼：

' Activity tracing information
My.Application.Log.WriteEntry("Entering Button1_Click", TraceEventType.Start)

' Tracing information
My.Application.Log.WriteEntry("In Button1_Click", TraceEventType.Information)

' Create an exception to log. 
Dim ex As New ApplicationException
' Exception information
My.Application.Log.WriteException(ex)

' Activity tracing information
My.Application.Log.WriteEntry("Leaving Button1_Click", TraceEventType.Stop)

在偵錯工具中執行應用程式。
按 [Button1]。

應用程式會將下列資訊寫入應用程式的偵錯輸出與記錄檔。

DefaultSource Information: 0 : In Button1_Click

DefaultSource Error: 2 : Error in the application.
請關閉應用程式。

如需如何檢視應用程式之偵錯輸出視窗的詳細資訊，請參閱輸出視窗。如需應用程式之記錄檔位置的詳細資訊，請參閱逐步解說：判斷 My.Application.Log 寫入資訊的位置 (Visual Basic)。

注意事項
根據預設，應用程式會在關閉時清除記錄檔輸出。

在上述範例中，WriteEntry 方法的第二個呼叫與 WriteException 方法的呼叫會記錄輸出，但 WriteEntry 方法的第一個與最後一個呼叫則不會。這是因為 WriteEntry 與 WriteException 的嚴重性層級是 "Information" 與 "Error"，My.Application.Log 物件的預設記錄篩選會接受這兩個層級。但是會阻止嚴重性層級為 "Start" 與 "Stop" 的事件產生記錄輸出。

所有 My.Application.Log 接聽程式的篩選

My.Application.Log 物件會使用名為 DefaultSwitch 的 SourceSwitch，控制它要將哪些訊息從 WriteEntry 與 WriteException 方法傳送到記錄接聽程式。您可以將 DefaultSwitch 的值設為 SourceLevels 列舉值的其中一個，藉以在應用程式的組態檔中設定它。根據預設，它的值為 "Information"。

此表會顯示「記錄檔」在特定的 DefaultSwitch 設定下，將訊息寫入接聽程式所需的嚴重性層級。

DefaultSwitch 值	輸出所需的訊息嚴重性
Critical	Critical
Error	Critical 或 Error
Warning	Critical、Error 或 Warning
Information	Critical、Error、Warning 或 Information
Verbose	Critical、Error、Warning、Information 或 Verbose
ActivityTracing	Start、Stop、Suspend、Resume 或 Transfer
All	接受所有訊息
Off	封鎖所有訊息

注意事項
WriteEntry 與 WriteException 方法都有不指定嚴重性層級的多載。WriteEntry 多載的隱含嚴重性層級是 "Information"，而 WriteException 多載的隱含嚴重性層級則是 "Error"。

此表會說明先前範例所示的記錄輸出 (其中 DefaultSwitch 的預設設定為 "Information")，只有 WriteEntry 方法的第二個呼叫與 WriteException 方法的呼叫會產生記錄輸出。

若只要記錄活動追蹤事件

以滑鼠右鍵按一下 [方案總管] 中的 [app.config]，並選取 [開啟]。

-或-

如果沒有 app.config 檔：
1. 在 [專案] 功能表中，選擇 [加入新項目]。
2. 從 [加入新項目] 對話方塊中選擇 [應用程式組態檔]。
3. 按一下 [加入]。
在最上層 <configuration> 區段的 <system.diagnostics> 區段中，尋找 <switches> 區段。
尋找將 DefaultSwitch 加入至參數集合的項目。它應該類似下列項目：

<add name="DefaultSwitch" value="Information" />
將 value 屬性 (Attribute) 的值變更為 "ActivityTracing"。

app.config 檔的內容應該和下列 XML 類似：‎

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <system.diagnostics>
    <sources>
      <!-- This section configures My.Application.Log -->
      <source name="DefaultSource" switchName="DefaultSwitch">
        <listeners>
          <add name="FileLog"/>
        </listeners>
      </source>
    </sources>
    <switches>
      <add name="DefaultSwitch" value="ActivityTracing" />
    </switches>
    <sharedListeners>
      <add name="FileLog"
           type="Microsoft.VisualBasic.Logging.FileLogTraceListener, 
                 Microsoft.VisualBasic, Version=8.0.0.0, 
                 Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a, 
                 processorArchitecture=MSIL" 
           initializeData="FileLogWriter"/>
    </sharedListeners>
  </system.diagnostics>
</configuration>

在偵錯工具中執行應用程式。
按 [Button1]。

應用程式會將下列資訊寫入應用程式的偵錯輸出與記錄檔：

DefaultSource Start: 4 : Entering Button1_Click

DefaultSource Stop: 5 : Leaving Button1_Click
請關閉應用程式。
將 value 屬性的值變回 "Information"。

注意事項
DefaultSwitch 參數設定只能控制 My.Application.Log。它不會變更 .NET Framework Trace 與 Debug 類別的行為表現方式。

My.Application.Log 接聽程式的個別篩選

先前範例會顯示如何變更所有 My.Application.Log 輸出的篩選。下列範例會篩選個別的記錄檔接聽程式。根據預設，應用程式會有兩個接聽程式，負責寫入應用程式的偵錯輸出與記錄檔。

組態檔允許每一個記錄檔接聽程式都有一個篩選條件，藉以控制記錄檔接聽程式的行為，這與 My.Application.Log 的參數類似。只有當這兩個記錄檔的 DefaultSwitch 與記錄檔接聽程式的篩選條件都接受訊息的嚴重性時，記錄檔接聽程式才會輸出訊息。

下列範例會為新的偵錯接聽程式設定篩選條件，並將此接聽程式加入至 Log 物件。應該將預設的偵錯接聽程式從 Log 物件中移除，這樣就能確定偵錯訊息是來自新的偵錯接聽程式。

若只要記錄活動追蹤事件

以滑鼠右鍵按一下 [方案總管] 的 [app.config]，並選擇 [開啟]。

-或-

如果沒有 app.config 檔：
1. 在 [專案] 功能表中，選擇 [加入新項目]。
2. 從 [加入新項目] 對話方塊中選擇 [應用程式組態檔]。
3. 按一下 [加入]。
以滑鼠右鍵按一下 [方案總管] 中的 [app.config]。選擇 [開啟]。
在 <sources> 區段下，於具有 name 屬性 "DefaultSource" 的 <source> 區段中，尋找 <listeners> 區段。 <sources> 區段是在最上層 <configuration> 區段的 <system.diagnostics> 區段下。

將這個項目加入至 <listeners> 區段：

<!-- Remove the default debug listener. -->
<remove name="Default"/>
<!-- Add a filterable debug listener. -->
<add name="NewDefault"/>

在最上層 <configuration> 區段的 <system.diagnostics> 區段中，尋找 <sharedListeners> 區段。

將這個項目加入至此 <sharedListeners> 區段：

<add name="NewDefault" 
     type="System.Diagnostics.DefaultTraceListener, 
           System, Version=2.0.0.0, Culture=neutral, 
           PublicKeyToken=b77a5c561934e089, 
           processorArchitecture=MSIL">
    <filter type="System.Diagnostics.EventTypeFilter" 
            initializeData="Error" />
</add>

EventTypeFilter 篩選條件會採取 SourceLevels 列舉值的其中一個做為 initializeData 屬性。

app.config 檔的內容應該和下列 XML 類似：‎

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <system.diagnostics>
    <sources>
      <!-- This section configures My.Application.Log -->
      <source name="DefaultSource" switchName="DefaultSwitch">
        <listeners>
          <add name="FileLog"/>
          <!-- Remove the default debug listener. -->
          <remove name="Default"/>
          <!-- Add a filterable debug listener. -->
          <add name="NewDefault"/>
        </listeners>
      </source>
    </sources>
    <switches>
      <add name="DefaultSwitch" value="Information" />
    </switches>
    <sharedListeners>
      <add name="FileLog"
           type="Microsoft.VisualBasic.Logging.FileLogTraceListener, 
                 Microsoft.VisualBasic, Version=8.0.0.0, 
                 Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a, 
                 processorArchitecture=MSIL" 
           initializeData="FileLogWriter"/>
      <add name="NewDefault" 
           type="System.Diagnostics.DefaultTraceListener, 
                 System, Version=2.0.0.0, Culture=neutral, 
                 PublicKeyToken=b77a5c561934e089, 
                 processorArchitecture=MSIL">
        <filter type="System.Diagnostics.EventTypeFilter" 
                initializeData="Error" />
      </add>
    </sharedListeners>
  </system.diagnostics>
</configuration>

在偵錯工具中執行應用程式。
按 [Button1]。

應用程式會將下列資訊寫入應用程式的記錄檔：

Default Information: 0 : In Button1_Click

Default Error: 2 : Error in the application.

因為篩選條件的限制更多，所以應用程式所寫入的資訊會較應用程式的偵錯輸出還要少。

Default Error 2 Error
請關閉應用程式。