Logging

.NET has a standard logging mechanism, but is has a limited number of built-in logging providers. Bulletcode.NET implements a TextFile provider, which is available in the Bulletcode.Common library and can be used in both desktop applications and in web applications, and a Database provider, which is available in the Bulletcode.Web.Core library.

To register the text and database providers in a web application, call the AddCoreLoggingProviders<TEvent>() extension method of the ILoggingBuilder. The TEvent type is a database entity used for logging events in the database; you can use either the Event type defined in Bulletcode.Web.Core, or a custom class which inherits Event.

To register the text provider in a desktop application, call the AddDesktopLoggingProviders() extension method.

Logging can be configured using the Logging section of the appsetings.json file. The LogLevel configuration can be specified globally for all providers and individually for each provider.

Configuring the TextFile provider

In the configuration subsection for the TextFile provider you can specify a custom DirectoryPath containing log files. The default value is "logs". The path is relative to the directory containing the application’s executable file. However, for desktop applications running in production environment, the DirectoryPath specified in the provider settings is treated as relative to the application name subfolder in the local application data directory.

In order to enable logging, you must also specify one or more targets. Each target contains the following options:

Threshold — The minimum log level which of messages which are included in the log file.
MaxCount — The maximum number of log files which are preserved. The default value is 0, which means that log files are never deleted.
IncludeScopes — If true, the values of all log scopes are also included for each logged message. For example, in web applications, scope information includes the request path and the remote IP address.

A separate text file is created every day, and the name of the file contains the name of the target and the current date. Each log entry starts with a date and time, log level, category name and event ID. The full exception stack trace is also logged if available.

For example, the following configuration can be used in appsettings.json:

{
  "Logging": {
    "TextFile": {
      "DirectoryPath": "logs",
      "LogLevel": {
        "Default": "Warning"
      },
      "Targets": {
        "error": {
          "Threshold": "Warning",
          "MaxCount": 30,
          "IncludeScopes": true
        }
      }
    }
  }
}

This enables logging warnings and errors, and up to 30 log files are preserved. To enable detailed logging during development, you can add the following configuration to appsettings.Development.json:

{
  "Logging": {
    "TextFile": {
      "LogLevel": {
        "Default": "Debug"
      },
      "Targets": {
        "debug": {
          "Threshold": "Debug",
          "MaxCount": 10
        }
      }
    }
  }
}

This adds a second logging target which stores all information with Debug level and above, and the last 10 log files are preserved.

Using the database provider

The database provider uses Entity Framework for logging events. The application should define a database context which inherits CoreDbContext, as described in the Database chapter. The built-in Event database entity stores the date and time, log level, category name, event ID and name, log message, and scope data serialized in JSON format. To make it easier to filter by scope, the request ID and path, IP address and user ID and name are also stored in separate columns.

The application can inherit the Event class and add custom properties. In this case, it should also override the built-in IEventFactory<TEvent> service, which creates instances of the event entity based on the log messages.

In the configuration subsection for the Database provider you can specify a custom CleanUpTimeSpan after which old entries are deleted. The default value is 30 days. For example:

{
  "Logging": {
    "Database": {
      "CleanUpTimeSpan": "30"
    }
  }
}

By default, ASP.NET Core includes information such as the request ID and request path, and the name of the executed action, as part of the scope data. Bulletcode.NET provides additional scope data, including the remote IP address and the authentication type and the ID and name of the authenticated user. To enable collecting this information, call the UseDiagnosticTags() extension method of the IApplicationBuilder.