TraceFilter.ShouldTrace Method

Definition

Namespace:

System.Diagnostics

Assembly:

System.Diagnostics.TraceSource.dll

Source:

TraceFilter.cs

When overridden in a derived class, determines whether the trace listener should trace the event.

public:
 abstract bool ShouldTrace(System::Diagnostics::TraceEventCache ^ cache, System::String ^ source, System::Diagnostics::TraceEventType eventType, int id, System::String ^ formatOrMessage, cli::array <System::Object ^> ^ args, System::Object ^ data1, cli::array <System::Object ^> ^ data);

public abstract bool ShouldTrace (System.Diagnostics.TraceEventCache? cache, string source, System.Diagnostics.TraceEventType eventType, int id, string? formatOrMessage, object?[]? args, object? data1, object?[]? data);

abstract member ShouldTrace : System.Diagnostics.TraceEventCache * string * System.Diagnostics.TraceEventType * int * string * obj[] * obj * obj[] -> bool

Public MustOverride Function ShouldTrace (cache As TraceEventCache, source As String, eventType As TraceEventType, id As Integer, formatOrMessage As String, args As Object(), data1 As Object, data As Object()) As Boolean

Parameters

cache

TraceEventCache

The TraceEventCache that contains information for the trace event.

source

String

The name of the source.

eventType

TraceEventType

One of the TraceEventType values specifying the type of event that has caused the trace.

id

Int32

A trace identifier number.

formatOrMessage

String

Either the format to use for writing an array of arguments specified by the args parameter, or a message to write.

args

Object[]

An array of argument objects.

data1

Object

A trace data object.

data

Object[]

An array of trace data objects.

Returns

Boolean

true to trace the specified event; otherwise, false.

Examples

The following code example shows how to override the ShouldTrace method to indicate tracing should occur when the trace event type of the event is equal to TraceEventType.Error.

public ref class ErrorFilter : TraceFilter
{
public:
    virtual bool ShouldTrace(TraceEventCache^ cache, String^ source,
        TraceEventType eventType, int id, String^ formatOrMessage,
        array<Object^>^ args, Object^ data, array<Object^>^ dataArray) override
    {
        return eventType == TraceEventType::Error;
    }
};

public class ErrorFilter : TraceFilter
{
    override public bool ShouldTrace(TraceEventCache cache, string source,
        TraceEventType eventType, int id, string formatOrMessage,
        object[] args, object data, object[] dataArray)
    {
        return eventType == TraceEventType.Error;
    }
}

Public Class ErrorFilter
    Inherits TraceFilter

    Public Overrides Function ShouldTrace ( cache As TraceEventCache, _
                source As String, eventType As TraceEventType, _
                id As Integer, formatOrMessage As String, _
                args As Object(), data As Object, _
                dataArray As Object() ) As Boolean
        If eventType = TraceEventType.Error Then
            Return True
        Else
            Return False
        End If
    End Function
End Class

Notes to Implementers

Implementations of this method should return true if the event specified by the passed parameters should be traced. Otherwise the method should return false. For example, a filter that allows only error events to pass through to the listener should inspect the eventType parameter and return true if the trace event type level is set to Error or greater; otherwise, it should return false.

Implementations of the method should be prepared to handle null in the following parameters: args, data1, data, formatOrMessage, and cache. If the parameter value is null, the parameter is not part of the event. For example, if the args parameter is null, it means that the event does not have any arguments. If the data parameter is null, then there are either one or no data objects. If there is one data object, it will be found in the data1 parameter. The reason for the distinction between a single data object and an array of data objects is for performance. There is no reason to create an object array if only one object is traced, as is normally the case. If the data parameter is not null, the data1 parameter must also not be null.

It is guaranteed that the source parameter is not null and not an empty string ("").

Implementations of the method can optionally throw the following exceptions:

• ArgumentNullException if source is null.

• ArgumentException if eventType is not one of the TraceEventType values.

• Exceptions unrelated to the implementation of the method. For example, a ThreadAbortException.