FAQ

• What is NLog?

  • NLog is a free and open source library which helps to write log messages.

• Why should I use NLog? I can just do file.WriteLine() or Console.WriteLine()

  • Beside writing to files or console, then NLog can also write to many other targets, like database, email, event viewer, trace etc.
  • Output can be written in standard formats like Json / Csv / Xml or simple plain text with support for structured logging
  • The output can be customized to include extra context like ${threadid} with help from Layout Renderers.
  • NLog can use background threads for asynchronous output writing, so application threads are less impacted by logging.
  • With a simple configuration file you can decide at runtime (after deployment), what to log and where! No need to restart the program or recycle the app pool!

• Is it free?

  • Yes, it's licensed under the BSD license, so you can use it in commercial (closed source) programs without problems.

• Show me the magic!

  • Check the tutorial to get started!

• Just show me a config example

  • voilà

• Why is NLog not working?!

  • Most problems are fixed by following the troubleshooting guide. If you think it's a bug, please check contributing.md and create a GitHub issue!

• Is NLog thread safe?

  • Yes NLog provides thread safety:
    • Creating new Logger is threadsafe
    • Writing LogEvents is threadsafe
    • Updating context containers like GDC / ScopeContext is threadsafe
    • Adding new LoggingRules or Targets using LoggingConfiguration.AddRule and ReconfigExistingLoggers is threadsafe
    • Performing Reload of LoggingConfiguration will cause LogEvents from active loggers to be dropped until reload has completed.
    • Changing values of existing rules and targets at run-time isn't thread-safe!

• Why is trace and debug logs missing in ASP.NET Core?

  • Check your appsettings.json

• How do I upgrade to NLog 4.x?

  • Check the 4.0 release post, there are some breaking changes.
  • Update all the NLog packages. The latest stable version is recommend.
  • When upgrading from NLog 4.1.0, please the next question.

• I have trouble updating NLog from 4.1.0

  • We take semver very serious! Because NLog is strong named, it's important to keep the assembly version of all major versions the same, otherwise every library build on 4.0.0 should be recompiled for every other 4.x release (4.1, 4.2 etc) - which is unwanted because of semver.
    In NLog 4.1.0 there was a mistake in the assembly version, which has been fixed in 4.1.1. Upgrading from NLog 4.1.0 to another version can give issues when using NuGet. This will result in the following error:

  Could not load file or assembly 'NLog' or one of its dependencies. The located assembly's manifest definition does not match the assembly reference. (Exception from HRESULT: 0x80131040)

  If you upgrade, remove or alter the <assemblybinding>, as explained at the 4.1.1 news post.

• Should I use Common Logging?

  • That's up to you. It has it pros and cons. The greatest advantage is that you can easily switch between logging implementations (NLog, Log4Net, EntLib). This can be very important if you’re writing a library yourself, then the user who's using your library can choose which implementation to use.

  • There are some downsides:

    • You are limited in some features, or some features aren't available at all (like context classes or event properties)
    • The performance is a bit lower.
    • The platform support is lower. For example, there is no Xamarin support or a specialized .Net 4.5 build
    • The progress is limited by NLog and Common logging.

• Which Common Logging version should I use?

  • As you may have noticed the latest version of Common Logging doesn't match the latest version of NLog - the latest Common Logging is build to NLog 4.1. But that is not a problem! Since NLog 4.0 the assembly version is fixed to 4.0.0.0 and because follow semver, you can use the latest version of NLog with Common.Logging.NLog41.

• When a library depends on NLog, what version of NLog should be used?

  • If you don't use the latest additions, then you should only update every NLog major version. As mentioned at the Common Logging version, we will keep the assembly version fixed. The end-user don't need <assemblybinding>-magic! So in short: your library should target NLog 4.0 and in the future NLog 5.0.

• How to properly log exceptions?

• How to log extra Context Information?

• How do I get the most optimal performance?

• How to handle environment specific configuration?

• How to load NLog configuration from non standard path?

• How to create NLog Logger for sub classes?

• How to create isolated NLog Logger for Addons and Plugins?

• How to wrap NLog Logger?

• How do I write custom Targets, layouts and layout renderers?

• How to do dependency injection with NLog?

• How could I combine programmatic configuration with XML configuration?