Note
If you ever want to change the underlying logging framework or are using Optimizely Digital Experience Platform (DXP), use the log abstraction `
EPiServer.Logging.LogManager`.
The Logging API shipped with Optimizely Content Management System (CMS) is an abstraction for writing log messages from the system. It is not meant to compete with existing logging frameworks such as log4net, as it merely works as a façade for such frameworks. To manage the configuration and output of the logger, refer to the API of the implementing framework.
The API is used internally by the CMS assemblies for all logging, but it also is open to be used by any third-party product or implementation. Use this API if you are developing modules and add-ons for the CMS platform.
Note
When you create new CMS sites using the Visual Studio integration, the package _EPiServer.Logging.Log4Net_ is installed by default, which is the log4net implementation of the API.
## Log a message
When you want to log a message, retrieve a logger instance using the `LogManager` class. Only retrieve the logger once for each class where it is used and store the logger in a static variable, such as:
This creates a logger instance with the same name as the type where it is instantiated, including namespace. It also is possible to explicitly pass in another type or name directly to the logger, which could be useful if you want to simulate log messages from another source. This method is guaranteed to return a new instance, regardless if any implementation is found, so you can safely use the logger without performing any null checks.
After the logger instance is available in your class, you can call any of the provided overloads, depending on the criticality of the message. The following examples show the Debug level, but equivalent methods are available for all other available levels (Trace, Information, Warning, Error, Critical) as well.
While the API exposes an `IsEnabled` method on the logger, you do not need to check this before writing a message because it is done before it tries to write the message. If there is a cost to constructing the log message, such as an expensive serialization of a value, use any of the overloads that takes a message formatter delegate and pass in a method that constructs your log message. This delegate is not called until the enabled state is verified, thus avoiding unnecessary work if the logger is disabled.
Note
Most of the logging methods of the logger are provided through extension methods, so it is necessary to import the `
EPiServer.Logging` namespace to get easy access to these.
## Backwards compatibility
If you are currently using log4net for logging and want to start using the new API in an existing project, there is a dedicated namespace called `EPiServer.Logging.Compatibility` that will help with the migration. This namespace contains a `LogManager` class and an` ILog` interface that matches their log4net equivalents which in most cases should enable a simple a search-and-replace between _log4net_ and _EPiServer.Logging.Compatibility_ to maintain the same logging.
Note
This compatibility layer only is suggested as a short term solution to speed up the migration and that we are recommending everyone to use the standard API in the longer term.
## Implement the API
CMS provides an implementation for log4net through the _EPiServer.Logging.Log4Net_ package but it is relatively simple for anyone to replace this implementation with another.
To create an implementation, there are two interfaces that need to be implemented; `ILogger` and `ILoggerFactory. ILogger` is responsible for writing a message of a specified level to the logging framework of choice and `ILoggerFactory` for creating new `ILogger` instances.
The implementation is registered by adding the `LoggerFactoryAttribute` to your assembly, defining the type of your logger factory. The type implementing `ILoggerFactory` is required to have a public parameter-less constructor.
The Logging API currently only supports one logger type and the API uses the first factory type it can find when it scans assemblies. Make sure you remove the _EPiServer.Logging.Log4Net_ assembly before you deploy another implementation.