The SocketTools .NET class includes a built-in facility for generating debugging output in the form of a log file that provides information about the internal functions that it is using and the data that is being exchanged between the client and server. This is commonly referred to in the documentation as generating a trace log or enabling function logging.

To provide logging functionality for your application, you must redistribute the SocketTools.TraceLog.dll library along with the the class library. This library is what performs the actual logging and must be placed in the same folder where your application is installed. Note that you cannot add this library as a reference to your project. It is used internally by SocketTools and cannot be used directly by your program.

To create a trace log, your application must set the TraceFile property to the name of a file, the TraceFlags property to the level of logging desired and then set the Trace property to true. The default level of logging, zero, specifies that general information about the function calls being made will be logged. The most detailed logging is provided by specifying a level of four. In that case, all data exchanged between your application and the remote host is logged. This provides the most information, however it also generates the largest log files. To disable logging, set the Trace property to false.

There are two important things that you need to consider when enabling trace logging. The first is that the log file is always appended to, never overwritten by the control. This means that the files can grow to be very large, particularly with trace that includes all of the data sent and received by your application. You can use the standard file I/O functions in your language to manage the log file or even write your own data out to the file. Each time the file is written to, SocketTools will open the file, append the logging data and then close the file; it will never keep the file open between operations. This is important because if your application terminates abnormally, it ensures all of the logging data has been written and there are no open file handles being held by that instance of the class. However, this does incur additional overhead and can impact the performance of your application. When possible, it is recommended that you enable logging around the code that you feel may be part of the problem you're trying to resolve, and then disable logging when it is no longer required. Simply enabling logging at the beginning of your application can result in unnecessarily large log files.

If your application uses multiple instances of the class, it is only necessary to enable logging in one of them. Once enabled, all network operations in the current thread will be logged, regardless of which instance has enabled logging.

---