Logging messages

One of the most important parts of any plugin is logging messages. Be it a piece of information, a warning or a bigger error, BepInEx provides functionality to log it all.
With BepInEx, you can use the following logging APIs:

• (Recommended) Logger APIs
• UnityEngine.Debug APIs
• System.Diagnostics.Trace APIs
• System.Console APIs

Whichever API you will use, BepInEx will write the logs to the console, Unity's output_log.txt and to BepInEx/LogOutput.log file.

Using Logger APIs

This is the recommended way for logging in plugins.

All BaseUnityPlugin instances have Logger property for logging:

[BepInPlugin("org.bepinex.myplugin", "Logger Test", "1.0.0.0")]
public class MyPlugin : BaseUnityPlugin
{
    void Awake()
    {
        Logger.LogInfo("This is information");
        Logger.LogWarning("This is a warning");
        Logger.LogError("This is an error");
    }
}

If BepInEx console is enabled via [the configuration](configuration), this will print

[Info   : Logger Test] This is information
[Warning: Logger Test] This is a warning
[Error  : Logger Test] This is an error

Notice that the log reports the message type and the message source.
When using BepInEx's own logging API, the log source (i.e. the plugin name is automatically reported).

Refer to ManualLogSource for all available logging API.

Advanced: Log sources and log listeners

BepInEx's logging system mimics that of System.Diagnostics.Trace API.
BepInEx allows to create log sources that can generate log events (i.e the messages) and log listeners that receive and process those log events.
All sources are linked to listeners via Logger class.

In most cases, you don't have to care about how the API works. However, in some cases you may want to register your own log sources to log messages.
In addition, sometimes you might need to process the log events to write them somewhere. This is where you use the manual APIs.

Registering log sources

A log source is a class that inherits from ILogSource.
The most basic implementation is ManualLogSource which exposes various convenience logging functions.

To register a log source, add it to Sources collection:

var myLogSource = new ManualLogSource("MyLogSource"); // The source name is shown in BepInEx log

// Register the source
BepInEx.Logging.Logger.Sources.Add(myLogSource);

myLogSource.LogInfo("Test"); // Will print [Info: MyLogSource] Test

// Remove the source to free resources
BepInEx.Logging.Logger.Sources.Remove(myLogSource);

Because ManualLogSource is so useful, you can use CreateLogSource(String) to automatically create and register a ManualLogSource.

That way the above example becomes

var myLogSource = BepInEx.Logging.Logger.CreateLogSource("MyLogSource");
myLogSource.LogInfo("Test");
BepInEx.Logging.Logger.Sources.Remove(myLogSource);

About log listeners

Log listeners are used to process messages from log sources. To create a log source, create a class that inherits ILogListener.
After that, register a log listener by adding it to Listeners.

By default, BepInEx itself registers the following listeners:

• ConsoleLogListener - writes all log messages to BepInEx console
• DiskLogListener - writes all log messages to BepInEx/LogOutput.log
• UnityLogListener - writes all log messages to Unity's output_log.txt

If you need to write a custom log listener, consider using the above ones as examples.