AF SDK Reference

AFTrace Class

Save PDF

TABLE OF CONTENTS

AFTrace Class

Save PDF

Last UpdatedNov 18, 2025
7 minute read

AFTrace Class

The AFTrace class provides a mechanism for generating trace events within the SDK to trace listeners.

Inheritance Hierarchy

SystemObject
OSIsoft.AF.DiagnosticsAFTrace

Namespace: OSIsoft.AF.Diagnostics
Assembly: OSIsoft.AFSDK (in OSIsoft.AFSDK.dll) Version: 3.1.1.1182

Syntax

public static class AFTrace

Public NotInheritable Class AFTrace

You do not need to declare an instance of a static class in order to access its members.

public ref class AFTrace abstract sealed

[<AbstractClassAttribute>]
[<SealedAttribute>]
type AFTrace =  class end

The AFTrace type exposes the following members.

Properties

	Name	Description
	TraceLevel	The overall trace level.

Methods

	Name	Description
	AddListener	Adds a TraceListener to the list of listeners that receive messages from AFTrace.
	AddTracingMethodNames	Adds the input names to the list of methods to ignore when determining the calling method.
	Flush	Flushes the trace output buffers, and causes buffered data to be written to the output listeners.
	GetTraceLevel	Returns the trace level for the object.
	IsTraced	Indicates if the specified level is traced.
	RemoveListener	Removes a TraceListener from the list of listeners that receive messages from AFTrace.
	SetTraceLevel(String)	Sets the overall TraceLevel to the specified string representation of the levels.
	SetTraceLevel(AFTraceSwitchLevel)	Sets the overall TraceLevel to the specified level.
	SetTraceLevel(AFAnalysis, AFTraceSwitchLevel)	Sets a trace level for an AFAnalysis object.
	SetTraceLevel(AFNotification, AFTraceSwitchLevel)	Sets the trace level for an AFNotification object.
	SetTraceLevel(AFObject, AFTraceSwitchLevel)	Sets the trace level for a specific object and its child objects.
	TraceData	Output a data trace event.
	TraceDetail	Output a detail trace event.
	TraceError	Output an error trace event.
	TraceEvent(Exception)	Output an error trace event for the exception.
	TraceEvent(AFTraceSwitchLevel, String)	Output a trace event with a message.
	TraceEvent(AFTraceSwitchLevel, String, Int32)	Output a trace event with a message and a duration.
	TraceEvent(AFTraceSwitchLevel, String, Object)	Output a trace event as a formatted message with a variable number of arguments.
	TraceInformation	Output an information trace event.
	TraceSummary	Output a summary trace event.
	TraceWarning	Output a warning trace event.

Remarks

Trace events are generated within the SDK to log information about an operation to the trace listeners. By default, the .NET 3.5 SDK installs a trace listener to log information to the PIMessageLog. The .NET 4 version of the SDK does not install a trace listener by default. The default trace output level and the loaded trace listeners are controlled by the settings in the AFTrace.config (for .NET 3.5) and AFTrace4.config (for .NET 4) files located in the all users application directory (e.g. 'C:\ProgramData\OSIsoft\AF'). These setting can be modified at runtime using methods of this class. If you are using .NET 3.5, please see What's New in PI AF 2018 SP3 Patch 2.

Examples

This is an example implementation of a TraceListener used to capture messages from AFTrace. See AFCase for an example of how to use this trace listener when running a case.

public class MyTraceListener : TraceListener
{
    private StringBuilder _msgLine;
    private List<string> _log = new List<string>();

    public MyTraceListener()
    {
        AFTrace.AddListener(this);
    }

    protected override void Dispose(bool disposing)
    {
        if (disposing) Close();
        base.Dispose(disposing);
    }

    public override void Close()
    {
        AFTrace.RemoveListener(this);
        base.Close();
    }

    public int Count
    {
        get { return _log.Count; }
    }

    public void Clear()
    {
        _log.Clear();
    }

    public IList<string> GetMessages()
    {
        return _log;
    }

    public override void Write(string message)
    {
        if (_msgLine == null)
            _msgLine = new StringBuilder();
        _msgLine.Append(message);
    }

    public override void WriteLine(string message)
    {
        if (_msgLine != null && _msgLine.Length > 0)
        {
            _msgLine.Append(message);
            _log.Add(_msgLine.ToString());
            _msgLine.Length = 0;
        }
        else
        {
            _log.Add(message);
        }
    }
}

Public Class MyTraceListener
    Inherits TraceListener

    Private _msgLine As StringBuilder

    Private _log As List(Of String) = New List(Of String)

    Public Sub New()
        MyBase.New()
        AFTrace.AddListener(Me)
    End Sub

    Protected Overrides Sub Dispose(ByVal disposing As Boolean)
        If disposing Then
            Close()
        End If
        MyBase.Dispose(disposing)
    End Sub

    Public Overrides Sub Close()
        AFTrace.RemoveListener(Me)
        MyBase.Close()
    End Sub

    Public ReadOnly Property Count As Integer
        Get
            Return _log.Count
        End Get
    End Property

    Public Sub Clear()
        _log.Clear()
    End Sub

    Public Function GetMessages() As IList(Of String)
        Return _log
    End Function

    Public Overrides Sub Write(ByVal message As String)
        If (_msgLine Is Nothing) Then
            _msgLine = New StringBuilder
        End If
        _msgLine.Append(message)
    End Sub

    Public Overrides Sub WriteLine(ByVal message As String)
        If ((Not (_msgLine) Is Nothing) _
                    AndAlso (_msgLine.Length > 0)) Then
            _msgLine.Append(message)
            _log.Add(_msgLine.ToString)
            _msgLine.Length = 0
        Else
            _log.Add(message)
        End If
    End Sub
End Class

No code example is currently available or this language may not be supported.

AF SDK Reference

AFTrace Class

Table of Contents

AFTrace Class

Inheritance Hierarchy

Syntax

Properties

Methods

Remarks

Examples

Version Information

AFSDK

See Also

Reference

In This Topic

Related Links