FileLogTraceListener 類別

定義

命名空間:

Microsoft.VisualBasic.Logging

組件:

Microsoft.VisualBasic.Forms.dll

來源:

FileLogTraceListener.vb

提供一個簡單的監聽器，將日誌輸出導向檔案。

public ref class FileLogTraceListener : System::Diagnostics::TraceListener

[System.Runtime.InteropServices.ComVisible(false)]
public class FileLogTraceListener : System.Diagnostics.TraceListener

[<System.Runtime.InteropServices.ComVisible(false)>]
type FileLogTraceListener = class
    inherit TraceListener

Public Class FileLogTraceListener
Inherits TraceListener

繼承

Object

MarshalByRefObject

TraceListener

FileLogTraceListener

屬性

ComVisibleAttribute

備註

該 FileLogTraceListener 課程提供自動化維護功能，根據需要每日或每個應用程式進行日誌檔案封存。 此自動歸檔功能有助於降低開發者與管理員的維護責任。

可以在集合Trace.Listeners中加入Debug.Listeners一個FileLogTraceListener實例，將日誌輸出重新導向到文字檔。 此類別的實例也可以加入 My.Application.Log 或 My.Log （針對網頁應用程式）加入 Visual Basic 應用程式中。 更多資訊請參閱 攻略：變更 My.Application.Log 寫入資訊的位置。

此級別的主要特點包括：

1. 檔案功能。 此類別產生的日誌檔案依據基底名稱與日期命名，並附有編號以區分日誌檔案與後續版本。 新的日誌檔案會根據需要建立。

   檔案名稱的明確形式為 baseName[-dateStamp][-version].log，其中：

   • 該 baseName 部分是基本對數名稱，由 BaseFileName 屬性指定。
   • 該 dateStamp 部分格式為「YYYY-MM-DD」，當 LogFileCreationSchedule 為 或 DailyWeekly時會顯示。
   • 若需要多個相同且 baseNamedateStampversion 的日誌檔，則該部分（正Integer數 ）會被加入檔名。

2. 多重類別實例。 如果該 FileLogTraceListener 類別的實例寫入正在使用的檔案：

   • 若該類別在同一程序中被其他實例 FileLogTraceListener 使用，則該類別會共享該檔案。
   • 如果該檔案被其他程序使用，類別會以下一個可用名稱建立新的日誌檔。

3. 螺紋安全。 這個 FileLogTraceListener 類別是執行緒安全的。 這讓你能安全地從多個執行緒寫訊息到日誌，而不必使用鎖。

Log-File 地理位置

• 此 Location 屬性需列 LogFileLocation 舉指定一個典型目錄來寫入日誌檔。

• 要將日誌寫入另一個位置，請將屬性設定 CustomLocation 為該位置。

Log-File 名稱

• 日誌檔的基礎名稱由 BaseFileName 屬性指定。
• 目前的日誌檔名稱可以從 FullLogFileName 屬性讀取。 它源自其他幾個屬性以及檔案系統中日誌的當前狀態。

原木維護

• 建立新日誌檔案的最低頻率由屬性 LogFileCreationSchedule 決定。 當值為 Daily 或 Weekly時，會至少每天或每週建立一次新的日誌檔，並在名稱中加入日期戳記 FullLogFileName 。
• 日誌檔的最大大小（以位元組為單位）由屬性 MaxFileSize 決定。 若日誌檔案大小超過此大小，會丟棄寫入日誌的額外訊息，並依屬性 DiskSpaceExhaustedBehavior 拋出例外。
• 該 ReserveDiskSpace 性質決定了必須有多少可用空間（以位元組為單位）。 這有助於確保 FileLogTraceListener 類別不會佔用所有可用的磁碟空間。 使用該 DiskSpaceExhaustedBehavior 屬性來指定當空閒位元組少 ReserveDiskSpace 於位元組時日誌寫入的行為。

Log-File 輸出設定

• 該 AutoFlush 性質指定了每次寫入日誌檔案後，底層串流是否應自動清除。
• 此 Append 屬性指定是否將訊息附加到目前的日誌檔案（若允許）或寫入新的日誌檔案。
• 屬性 Delimiter 指定了用於分隔日誌訊息欄位的字串。
• 該 Encoding 屬性指定建立新日誌檔案時所使用的編碼方式。

Log-File 輸出

• 和 TraceEvent 方法將TraceData訊息寫入日誌檔案。 這些方法會檢查 LogFileCreationSchedule 該屬性，以及任何已擁有相同基底名稱的原木，以判斷是否需要建立新的原木。
• 此 Flush 方法會將目前輸出緩衝區中的所有訊息清除到日誌檔。
• 此 Close 方法關閉日誌檔，使其能被其他程序使用。

啟用輸出

你必須啟用追蹤或除錯才能使用追蹤監聽器。 以下語法是編譯器專屬的。 如果你使用非 C# 或 Visual Basic 的編譯器，請參考你編譯器的文件。

• 要啟用 C# 除錯，編譯時在編譯器命令列加入 /d:DEBUG 旗標，或者你可以在檔案頂端新增 #define DEBUG 標記。 在 Visual Basic 中，將旗標加入 /d:DEBUG=True 編譯器命令列。
• 要啟用 C# 的追蹤，編譯程式碼時可以在編譯器命令列加入 /d:TRACE 該標誌，或在檔案頂端新增 #define TRACE 標記。 在 Visual Basic 中，將旗標加入 /d:TRACE=True 編譯器命令列。

在 .NET Framework 應用程式中，你可以透過編輯應用程式的設定檔來設定監聽器的等級。 在此檔案中，您可以新增監聽器、設定其類型與參數、移除監聽器，或清除應用程式先前設定的所有監聽器。 設定檔的格式應如以下範例所示。

<configuration>
    <system.diagnostics>
        <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>

要執行此範例，您必須提供完全合格的組裝名稱。 關於如何取得完全合格的議會名稱，請參閱議會名稱。

建構函式

名稱	Description
FileLogTraceListener()	初始化一個以預設名稱的新 FileLogTraceListener 類別實例。
FileLogTraceListener(String)	初始化一個新的類別實例 FileLogTraceListener ，並使用所提供名稱。

屬性

名稱	Description
Append	決定是否將輸出附加到目前檔案，或寫入新檔案或現有檔案。
AutoFlush	表示寫入日誌檔案串流是否會清除緩衝區。
BaseFileName	取得或設定日誌檔案的基礎名稱，用以建立完整的日誌檔案名稱。
CustomLocation	當屬性 Location 設定為 Custom時，取得或設定日誌檔案目錄。
Delimiter	取得或設定用於分隔日誌訊息欄位的分隔符。
DiskSpaceExhaustedBehavior	決定寫入日誌檔案時該怎麼做，且可用磁碟空間比屬性指定 ReserveDiskSpace 的少。
Encoding	取得或設定編碼，用於建立新的日誌檔案。
FullLogFileName	會取得目前完整的日誌檔名稱。
IncludeHostName	指示是否應將日誌機的主機名稱納入輸出。
Location	取得或設定日誌檔案的位置。
LogFileCreationSchedule	決定日誌檔案名稱中包含哪個日期。
MaxFileSize	取得或設定日誌檔案的最大允許大小（以位元組為單位）。
ReserveDiskSpace	取得或設定在可寫入日誌檔案前所需的可用磁碟空間（位元組）。

方法

名稱	Description
Close()	關閉目前日誌檔案的底層串流，並釋放與該串流相關的所有資源。
Dispose(Boolean)	關閉底層串流，並可選擇性地釋放受管理資源。
Flush()	清除寫入當前日誌檔的底層串流。
GetSupportedAttributes()	取得追蹤監聽器支援的自訂 XML 設定屬性。
TraceData(TraceEventCache, String, TraceEventType, Int32, Object)	會將追蹤資訊、資料物件和事件資訊寫入輸出檔案或串流。
TraceData(TraceEventCache, String, TraceEventType, Int32, Object[])	會將追蹤資訊、資料物件陣列及事件資訊寫入輸出檔案或串流。
TraceEvent(TraceEventCache, String, TraceEventType, Int32, String, Object[])	將追蹤資訊、格式化的物件陣列及事件資訊寫入輸出檔案或串流。
TraceEvent(TraceEventCache, String, TraceEventType, Int32, String)	會將追蹤資訊、訊息及事件資訊寫入輸出檔案或串流。
Write(String)	將訊息逐字寫入磁碟，且不需額外上下文資訊。
WriteLine(String)	會逐字寫入一則訊息到磁碟，接著是當前的行終止符，且不需額外上下文資訊。

另請參閱

• BaseFileName
• TraceData(TraceEventCache, String, TraceEventType, Int32, Object)
• TraceEvent(TraceEventCache, String, TraceEventType, Int32, String)
• Flush()
• Close()
• 逐步解說：變更 My.Application.Log 寫入資訊的位置