2.x Upgrade Guide

Serilog 2.0 adds to the performance and reliability of the earlier Serilog releases, while aligning Serilog's packaging with the needs of new .NET targets including .NET Core and Linux. Very minimal breaking changes have been made where necessary - practically all code written against Serilog 1.5 will recompile against Serilog 2.0 without errors.

Platform support

Serilog 2.0 no longer supports .NET 4.0. Applications targeting .NET 4.0 can continue to use the Serilog 1.5 series of packages or update to .NET 4.5.2.

Updating to Serilog 2.0

The core Serilog package is Serilog. At the Visual Studio Package Manager Console:

Update-Package Serilog

All projects used in a Serilog 2.0 application should be upgraded and rebuilt. Although source compatibility has been maintained, the old Serilog.FullNetFx assembly has been removed, and types in it such as LogContext moved into the core Serilog package. Failing to upgrade projects can lead to TypeLoadException being thrown at runtime.

NuGet version requirements

Errors installing the NuGet package, mentioning Microsoft.CSharp or failing to find the package entirely, may indicate that the version of NuGet.exe is out-of-date. NuGet version 3.0 or better is required to install the Serilog package.

Visual Studio 2013 users can install the updated NuGet Package Manager Extension that adds support for packages targeting the .NET Platform Standard.

Installing 2.0 sink packages

In Serilog 1.5, the core sinks, including Console, ColoredConsole, File, RollingFile and so-on were part of the Serilog packages. These are now separate.

To install the new Console sink, use:

Install-Package Serilog.Sinks.Console

The names of sink packages are consistent so that it's easy to guess the correct name, with very few exceptions:

Sink name	WriteTo.*	Package
Colored Console	ColoredConsole	Serilog.Sinks.ColoredConsole
Console	Console	Serilog.Sinks.Console
File	File	Serilog.Sinks.File
Observable	Observers	Serilog.Sinks.Observable
Periodic Batching		Serilog.Sinks.PeriodicBatching
Rolling File	RollingFile	Serilog.Sinks.RollingFile
TextWriter	TextWriter	Serilog.Sinks.TextWriter
Trace	Trace	Serilog.Sinks.Trace

Installing 2.0 enricher packages

If your application uses any of the built-in enrichers such as machine name or thread, you'll need to install the corresponding package:

Install-Package Serilog.Enrichers.Environment

The three packages that were previously included in the core Serilog package are:

Enricher package	Enrich.*
Serilog.Enrichers.Environment	MachineName, UserName
Serilog.Enrichers.Process	ProcessId
Serilog.Enrichers.Thread	ThreadId

XML <appSettings> support

This has moved to Serilog.Settings.AppSettings:

Install-Package Serilog.Settings.AppSettings

Shutting down or disposing the logger

If your application uses any network-based or asynchronous sinks, Serilog 2.0 requires you to explicitly shut down the logging pipeline so that queued events are properly flushed before the application exits.

It's not strictly necessary to add this code if you only use local file/console logging, but considered best practice to do so anyway.

(This change makes Serilog's behavior consistent across platforms, including .NET Core, where AppDomain unloading events are no longer available).

If you use the static Log class:

Log.CloseAndFlush();

Or otherwise, if you use the return value of CreateLogger() directly, you will need to call Dispose() on it.

This can be done:

• At the end of Main()
• In the Application_End() method of ASP.NET's Global.asax

Implementing ILogger

If your application or library implements Serilog's ILogger, several methods have been added in Serilog 2.0 that will need to be accounted for.

• Write(), Verbose(), Debug(), Information(), Warning(), Error() and Fatal() now have generic overloads that avoid allocations when logging is disabled; these otherwise behave the same as the existing methods with those names
• ForContext(ILogEventEnricher) has been added
• BindMessageTemplate() and BindProperty() have been added; most implementations can ignore these and return false

LogContext changes

Some longstanding issues in the LogContext feature have been fixed in 2.0. This means that LogContext.Suspend() and LogContext.PermitCrossAppDomainCalls are no longer necessary in any scenario, and so have been removed. If your code uses these members, just remove the usages and everything should now "just work".

Getting help

If you need help with an upgrade to Serilog 2.0, please post your question at Stack Overflow. This will allow the widest group of people to assist you, as well as make the answer visible for others in a similar situation. Thanks!