src/log4net/Appender/TraceAppender.cs

#region Apache License
//
// Licensed to the Apache Software Foundation (ASF) under one or more 
// contributor license agreements. See the NOTICE file distributed with
// this work for additional information regarding copyright ownership. 
// The ASF licenses this file to you under the Apache License, Version 2.0
// (the "License"); you may not use this file except in compliance with 
// the License. You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
#endregion

#define TRACE

using log4net.Layout;
using log4net.Core;

namespace log4net.Appender;

/// <summary>
/// Appends log events to the <see cref="System.Diagnostics.Trace"/> system.
/// </summary>
/// <remarks>
/// <para>
/// The application configuration file can be used to control what listeners 
/// are actually used. See the MSDN documentation for the 
/// <see cref="System.Diagnostics.Trace"/> class for details on configuring the
/// trace system.
/// </para>
/// <para>
/// Events are written using the <c>System.Diagnostics.Trace.Write(string,string)</c>
/// method. The event's logger name is the default value for the category parameter 
/// of the Write method. 
/// </para>
/// <para>
/// <b>Compact Framework</b><br />
/// The Compact Framework does not support the <see cref="System.Diagnostics.Trace"/>
/// class for any operation except <c>Assert</c>. When using the Compact Framework this
/// appender will write to the <see cref="System.Diagnostics.Debug"/> system rather than
/// the Trace system. This appender will therefore behave like the <see cref="DebugAppender"/>.
/// </para>
/// </remarks>
/// <author>Douglas de la Torre</author>
/// <author>Nicko Cadell</author>
/// <author>Gert Driesen</author>
/// <author>Ron Grabowski</author>
public class TraceAppender : AppenderSkeleton
{
  /// <summary>
  /// Gets or sets a value that indicates whether the appender will 
  /// flush at the end of each write.
  /// </summary>
  /// <remarks>
  /// <para>The default behavior is to flush at the end of each 
  /// write. If the option is set to<c>false</c>, then the underlying 
  /// stream can defer writing to physical medium to a later time. 
  /// </para>
  /// <para>
  /// Avoiding the flush operation at the end of each append results 
  /// in a performance gain of 10 to 20 percent. However, there is safety
  /// trade-off involved in skipping flushing. Indeed, when flushing is
  /// skipped, then it is likely that the last few log events will not
  /// be recorded on disk when the application exits. This is a high
  /// price to pay even for a 20% performance gain.
  /// </para>
  /// </remarks>
  public bool ImmediateFlush { get; set; } = true;

  /// <summary>
  /// The category parameter sent to the Trace method.
  /// </summary>
  /// <remarks>
  /// <para>
  /// Defaults to %logger which will use the logger name of the current 
  /// <see cref="LoggingEvent"/> as the category parameter.
  /// </para>
  /// </remarks>
  public PatternLayout Category { get; set; } = new("%logger");

  /// <summary>
  /// Writes the logging event to the <see cref="System.Diagnostics.Trace"/> system.
  /// </summary>
  /// <param name="loggingEvent">The event to log.</param>
  protected override void Append(LoggingEvent loggingEvent)
  {
    System.Diagnostics.Trace.Write(RenderLoggingEvent(loggingEvent), Category.Format(loggingEvent));

    if (ImmediateFlush)
    {
      System.Diagnostics.Trace.Flush();
    }
  }

  /// <summary>
  /// This appender requires a <see cref="Layout"/> to be set.
  /// </summary>
  protected override bool RequiresLayout => true;

  /// <summary>
  /// Flushes any buffered log data.
  /// </summary>
  /// <param name="millisecondsTimeout">The maximum time to wait for logging events to be flushed.</param>
  /// <returns><c>True</c> if all logging events were flushed successfully, else <c>false</c>.</returns>
  public override bool Flush(int millisecondsTimeout)
  {
    // Nothing to do if ImmediateFlush is true
    if (ImmediateFlush)
    {
      return true;
    }

    // System.Diagnostics.Trace and System.Diagnostics.Debug are thread-safe, so no need for lock.
    System.Diagnostics.Trace.Flush();
    return true;
  }
}