|
1 | | -# Serilog.Sinks.Console |
| 1 | +# Serilog.Sinks.Console [](https://ci.appveyor.com/project/serilog/serilog-sinks-console/branch/master) [](https://www.nuget.org/packages/Serilog.Sinks.Console/) [](https://github.com/serilog/serilog/wiki) [](https://gitter.im/serilog/serilog) [](http://stackoverflow.com/questions/tagged/serilog) |
2 | 2 |
|
3 | | -The console sink for Serilog. |
4 | | - |
5 | | -[](https://ci.appveyor.com/project/serilog/serilog-sinks-console/branch/master) [](https://www.nuget.org/packages/Serilog.Sinks.Console/) |
| 3 | +A Serilog sink that writes log events to the Windows Console or an ANSI terminal via standard output. Coloring and custom themes are supported, including ANSI 256-color themes on macOS, Linux and Windows 10. The default output is plain text; JSON formatting can be plugged in using a package such as [_Serilog.Formatting.Compact_](https://github.com/serilog/serilog-formatting-compact). |
6 | 4 |
|
7 | | -Writes to the system console. The colored console sink's boring cousin. |
| 5 | +### Getting started |
8 | 6 |
|
9 | | -To use the console sink, first install the NuGet package: |
| 7 | +To use the console sink, first install the [NuGet package](https://nuget.org/packages/serilog.sinks.console): |
10 | 8 |
|
11 | 9 | ```powershell |
12 | 10 | Install-Package Serilog.Sinks.Console |
13 | 11 | ``` |
14 | 12 |
|
| 13 | +Then enable the sink using `WriteTo.Console()`: |
| 14 | + |
15 | 15 | ```csharp |
16 | | -var log = new LoggerConfiguration() |
| 16 | +Log.Logger = new LoggerConfiguration() |
17 | 17 | .WriteTo.Console() |
18 | 18 | .CreateLogger(); |
| 19 | + |
| 20 | +Log.Information("Hello, world!"); |
| 21 | +``` |
| 22 | + |
| 23 | +Log events will be printed to `STDOUT`: |
| 24 | + |
| 25 | +``` |
| 26 | +[12:50:51 INF] Hello, world! |
| 27 | +``` |
| 28 | + |
| 29 | +### Themes |
| 30 | + |
| 31 | +The sink will colorize output by default: |
| 32 | + |
| 33 | + |
| 34 | + |
| 35 | +Themes can be specified when configuring the sink: |
| 36 | + |
| 37 | +```csharp |
| 38 | + .WriteTo.Console(theme: AnsiConsoleTheme.Code) |
| 39 | +``` |
| 40 | + |
| 41 | +The following built-in themes are available: |
| 42 | + |
| 43 | + * `ConsoleTheme.None` - no styling |
| 44 | + * `SystemConsoleTheme.Literate` - styled to replicate _Serilog.Sinks.Literate_, using the `System.Console` coloring modes supported on all Windows/.NET targets; **this is the default when no theme is specified** |
| 45 | + * `SystemConsoleTheme.Grayscale` - a theme using only shades of gray, white, and black |
| 46 | + * `AnsiConsoleTheme.Literate` - an ANSI 16-color version of the "literate" theme; we expect to update this to use 256-colors for a more refined look in future |
| 47 | + * `AnsiConsoleTheme.Grayscale` - an ANSI 256-color version of the "grayscale" theme |
| 48 | + * `AnsiConsoleTheme.Code` - an ANSI 256-color Visual Studio Code-inspired theme |
| 49 | + |
| 50 | + Adding a new theme is straightforward; examples can be found in the [`SystemConsoleThemes`](https://github.com/serilog/serilog-sinks-console/blob/dev/src/Serilog.Sinks.Console/Sinks/SystemConsole/Themes/SystemConsoleThemes.cs) and [`AnsiConsoleThemes`](https://github.com/serilog/serilog-sinks-console/blob/dev/src/Serilog.Sinks.Console/Sinks/SystemConsole/Themes/AnsiConsoleThemes.cs) classes. |
| 51 | + |
| 52 | +### Output templates |
| 53 | + |
| 54 | +The format of events to the console can be modified using the `outputTemplate` configuration parameter: |
| 55 | + |
| 56 | +```csharp |
| 57 | + .WriteTo.Console( |
| 58 | + outputTemplate: "[{Timestamp:HH:mm:ss} {Level:u3}] {Message:lj}{NewLine}{Exception}") |
| 59 | +``` |
| 60 | + |
| 61 | +The default template, shown in the example above, uses built-in properties like `Timestamp` and `Level`. Properties from events, including those attached using [enrichers](https://github.com/serilog/serilog/wiki/Enrichment), can also appear in the output template. |
| 62 | + |
| 63 | +### JSON output |
| 64 | + |
| 65 | +The sink can write JSON output instead of plain text. `CompactJsonFormatter` or `RenderedCompactJsonFormatter` from [Serilog.Formatting.Compact](https://github.com/serilog/serilog-formatting-compact) is recommended: |
| 66 | + |
| 67 | +```powershell |
| 68 | +Install-Package Serilog.Formatting.Compact |
| 69 | +``` |
| 70 | + |
| 71 | +Pass a formatter to the `Console()` configuration method: |
| 72 | + |
| 73 | +```csharp |
| 74 | + .WriteTo.Console(new CompactJsonFormatter()) |
| 75 | +``` |
| 76 | + |
| 77 | +Output theming is not available when custom formatters are used. |
| 78 | + |
| 79 | +### XML `<appSettings>` configuration |
| 80 | + |
| 81 | +To use the console sink with the [Serilog.Settings.AppSettings](https://github.com/serilog/serilog-settings-appsettings) package, first install that package if you haven't already done so: |
| 82 | + |
| 83 | +```powershell |
| 84 | +Install-Package Serilog.Settings.AppSettings |
| 85 | +``` |
| 86 | + |
| 87 | +Instead of configuring the logger in code, call `ReadFrom.AppSettings()`: |
| 88 | + |
| 89 | +```csharp |
| 90 | +var log = new LoggerConfiguration() |
| 91 | + .ReadFrom.AppSettings() |
| 92 | + .CreateLogger(); |
| 93 | +``` |
| 94 | + |
| 95 | +In your application's `App.config` or `Web.config` file, specify the console sink assembly under the `<appSettings>` node: |
| 96 | + |
| 97 | +```xml |
| 98 | +<configuration> |
| 99 | + <appSettings> |
| 100 | + <add key="serilog:using:Console" value="Serilog.Sinks.Console" /> |
| 101 | + <add key="serilog:write-to:Console" /> |
| 102 | +``` |
| 103 | + |
| 104 | +### JSON `appsettings.json` configuration |
| 105 | + |
| 106 | +To use the console sink with _Microsoft.Extensions.Configuration_, for example with ASP.NET Core or .NET Core, use the [Serilog.Settings.Configuration](https://github.com/serilog/serilog-settings-configuration) package. First install that package if you have not already done so: |
| 107 | + |
| 108 | +```powershell |
| 109 | +Install-Package Serilog.Settings.Configuration |
| 110 | +``` |
| 111 | + |
| 112 | +Instead of configuring the sink directly in code, call `ReadFrom.Configuration()`: |
| 113 | + |
| 114 | +```csharp |
| 115 | +var configuration = new ConfigurationBuilder() |
| 116 | + .AddJsonFile("appsettings.json") |
| 117 | + .Build(); |
| 118 | + |
| 119 | +var logger = new LoggerConfiguration() |
| 120 | + .ReadFrom.Configuration(configuration) |
| 121 | + .CreateLogger(); |
| 122 | +``` |
| 123 | + |
| 124 | +In your `appsettings.json` file, under the `Serilog` node, : |
| 125 | + |
| 126 | +```json |
| 127 | +{ |
| 128 | + "Serilog": { |
| 129 | + "WriteTo": [{"Name": "Console"}] |
| 130 | + } |
| 131 | +} |
| 132 | +``` |
| 133 | + |
| 134 | +### Upgrading from _Serilog.Sinks.Console_ 2.x |
| 135 | + |
| 136 | +To achieve output identical to version 2 of this sink, specify a formatter and output template explicitly: |
| 137 | + |
| 138 | +```csharp |
| 139 | + .WriteTo.Console(new MessageTemplateTextFormatter( |
| 140 | + "{Timestamp:yyyy-MM-dd HH:mm:ss} [{Level}] {Message}{NewLine}{Exception}", |
| 141 | + null)) |
19 | 142 | ``` |
20 | 143 |
|
21 | | -* [Documentation](https://github.com/serilog/serilog/wiki) |
| 144 | +This will bypass theming and use Serilog's built-in message template formatting. |
22 | 145 |
|
23 | | -Copyright © 2016 Serilog Contributors - Provided under the [Apache License, Version 2.0](http://apache.org/licenses/LICENSE-2.0.html). |
| 146 | +_Copyright © 2017 Serilog Contributors - Provided under the [Apache License, Version 2.0](http://apache.org/licenses/LICENSE-2.0.html)._ |
0 commit comments