Merge pull request #1 from serilog/dev

Merge

Author: EamonHetherton

.editorconfig

@@ -1,5 +1,16 @@
-root=true
+root = true
 
 [*]
+trim_trailing_whitespace = true
+insert_final_newline = true
 indent_style = space
 indent_size = 4
+
+[*.{csproj,json,config,yml,props}]
+indent_size = 2
+
+[*.sh]
+end_of_line = lf
+
+[*.{cmd, bat}]
+end_of_line = crlf

.gitignore

@@ -26,6 +26,9 @@ bld/
 # Uncomment if you have tasks that create the project's static files in wwwroot
 #wwwroot/
 
+# Rider cache/options directory
+.idea
+
 # MSTest test Results
 [Tt]est[Rr]esult*/
 [Bb]uild[Ll]og.*
@@ -234,3 +237,4 @@ _Pvt_Extensions
 
 # FAKE - F# Make
 .fake/
+example/Sample/log.txt

.travis.yml

@@ -0,0 +1,11 @@
+language: csharp
+
+matrix:
+  include:
+    - os: linux
+      dist: trusty
+      sudo: required
+      dotnet: 2.1.300
+      group: edge
+script:
+  - ./build.sh

Build.ps1

@@ -1,27 +1,46 @@
+echo "build: Build started"
+
 Push-Location $PSScriptRoot
 
-if(Test-Path .\artifacts) { Remove-Item .\artifacts -Force -Recurse }
+if(Test-Path .\artifacts) {
+	echo "build: Cleaning .\artifacts"
+	Remove-Item .\artifacts -Force -Recurse
+}
 
 & dotnet restore --no-cache
 
 $branch = @{ $true = $env:APPVEYOR_REPO_BRANCH; $false = $(git symbolic-ref --short -q HEAD) }[$env:APPVEYOR_REPO_BRANCH -ne $NULL];
 $revision = @{ $true = "{0:00000}" -f [convert]::ToInt32("0" + $env:APPVEYOR_BUILD_NUMBER, 10); $false = "local" }[$env:APPVEYOR_BUILD_NUMBER -ne $NULL];
-$suffix = @{ $true = ""; $false = "$branch-$revision"}[$branch -eq "master" -and $revision -ne "local"]
+$suffix = @{ $true = ""; $false = "$($branch.Substring(0, [math]::Min(10,$branch.Length)))-$revision"}[$branch -eq "master" -and $revision -ne "local"]
+$commitHash = $(git rev-parse --short HEAD)
+$buildSuffix = @{ $true = "$($suffix)-$($commitHash)"; $false = "$($branch)-$($commitHash)" }[$suffix -ne ""]
+
+echo "build: Package version suffix is $suffix"
+echo "build: Build version suffix is $buildSuffix" 
 
-foreach ($src in ls src/Serilog.*) {
+foreach ($src in ls src/*) {
     Push-Location $src
 
-    & dotnet pack -c Release -o ..\..\.\artifacts --version-suffix=$suffix
+	echo "build: Packaging project in $src"
+
+    & dotnet build -c Release --version-suffix=$buildSuffix -p:EnableSourceLink=true
+    if ($suffix) {
+        & dotnet pack -c Release -o ..\..\artifacts --version-suffix=$suffix --no-build
+    } else {
+        & dotnet pack -c Release -o ..\..\artifacts --no-build
+    }
     if($LASTEXITCODE -ne 0) { exit 1 }    
 
     Pop-Location
 }
 
-foreach ($test in ls test/Serilog.*.Tests) {
+foreach ($test in ls test/*.Tests) {
     Push-Location $test
 
+	echo "build: Testing project in $test"
+
     & dotnet test -c Release
-    if($LASTEXITCODE -ne 0) { exit 2 }
+    if($LASTEXITCODE -ne 0) { exit 3 }
 
     Pop-Location
 }

README.md

@@ -1,53 +1,196 @@
 # Serilog.Sinks.File [![Build status](https://ci.appveyor.com/api/projects/status/hh9gymy0n6tne46j?svg=true)](https://ci.appveyor.com/project/serilog/serilog-sinks-file) [![NuGet Version](http://img.shields.io/nuget/v/Serilog.Sinks.File.svg?style=flat)](https://www.nuget.org/packages/Serilog.Sinks.File/) [![Documentation](https://img.shields.io/badge/docs-wiki-yellow.svg)](https://github.com/serilog/serilog/wiki) [![Join the chat at https://gitter.im/serilog/serilog](https://img.shields.io/gitter/room/serilog/serilog.svg)](https://gitter.im/serilog/serilog)
 
-Writes [Serilog](https://serilog.net) events to a text file.
+Writes [Serilog](https://serilog.net) events to one or more text files.
+
+### Getting started
+
+Install the [Serilog.Sinks.File](https://www.nuget.org/packages/Serilog.Sinks.File/) package from NuGet:
+
+```powershell
+Install-Package Serilog.Sinks.File
+```
+
+To configure the sink in C# code, call `WriteTo.File()` during logger configuration:
 
 ```csharp
 var log = new LoggerConfiguration()
-    .WriteTo.File("log.txt")
+    .WriteTo.File("log.txt", rollingInterval: RollingInterval.Day)
     .CreateLogger();
 ```
 
-To avoid bringing down apps with runaway disk usage the file sink **limits file size to 1GB by default**. The limit can be increased or removed using the `fileSizeLimitBytes` parameter.
+This will append the time period to the filename, creating a file set like:
+
+```
+log20180631.txt
+log20180701.txt
+log20180702.txt
+```
+
+> **Important**: By default, only one process may write to a log file at a given time. See _Shared log files_ below for information on multi-process sharing.
+
+### Limits
+
+To avoid bringing down apps with runaway disk usage the file sink **limits file size to 1GB by default**. Once the limit is reached, no further events will be written until the next roll point (see also: [Rolling policies](#rolling-policies) below).
+
+The limit can be changed or removed using the `fileSizeLimitBytes` parameter.
 
 ```csharp
     .WriteTo.File("log.txt", fileSizeLimitBytes: null)
+``` 
+
+For the same reason, only **the most recent 31 files** are retained by default (i.e. one long month). To change or remove this limit, pass the `retainedFileCountLimit` parameter.
+
+```csharp
+    .WriteTo.File("log.txt", rollingInterval: RollingInterval.Day, retainedFileCountLimit: null)
+```
+
+### Rolling policies
+
+To create a log file per day or other time period, specify a `rollingInterval` as shown in the examples above.
+
+To roll when the file reaches `fileSizeLimitBytes`, specify `rollOnFileSizeLimit`:
+
+```csharp
+    .WriteTo.File("log.txt", rollOnFileSizeLimit: true)
+```
+
+This will create a file set like:
+
+```
+log.txt
+log_001.txt
+log_002.txt
+```
+
+Specifying both `rollingInterval` and `rollOnFileSizeLimit` will cause both policies to be applied, while specifying neither will result in all events being written to a single file.
+
+Old files will be cleaned up as per `retainedFileCountLimit` - the default is 31.
+
+### XML `<appSettings>` configuration
+
+To use the file 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:
+
+```powershell
+Install-Package Serilog.Settings.AppSettings
+```
+
+Instead of configuring the logger in code, call `ReadFrom.AppSettings()`:
+
+```csharp
+var log = new LoggerConfiguration()
+    .ReadFrom.AppSettings()
+    .CreateLogger();
+```
+
+In your application's `App.config` or `Web.config` file, specify the file sink assembly and required path format under the `<appSettings>` node:
+
+```xml
+<configuration>
+  <appSettings>
+    <add key="serilog:using:File" value="Serilog.Sinks.File" />
+    <add key="serilog:write-to:File.path" value="log.txt" />
+```
+
+The parameters that can be set through the `serilog:write-to:File` keys are the method parameters accepted by the `WriteTo.File()` configuration method. This means, for example, that the `fileSizeLimitBytes` parameter can be set with:
+
+```xml
+    <add key="serilog:write-to:File.fileSizeLimitBytes" value="1234567" />
 ```
 
-> **Important:** By default only one process may use a log file at a given time. See _Shared log files_ below if multi-process logging is required. 
+Omitting the `value` will set the parameter to `null`:
 
-### `<appSettings>` configuration
+```xml
+    <add key="serilog:write-to:File.fileSizeLimitBytes" />
+```
 
-The sink can be configured in XML [app-settings format](https://github.com/serilog/serilog/wiki/AppSettings) if the _Serilog.Settings.AppSettings_ package is in use:
+In XML and JSON configuration formats, environment variables can be used in setting values. This means, for instance, that the log file path can be based on `TMP` or `APPDATA`:
 
 ```xml
-<add key="serilog:using:File" value="Serilog.Sinks.File" />
-<add key="serilog:write-to:File.path" value="log.txt" />
-<add key="serilog:write-to:File.fileSizeLimitBytes" value="" />
+    <add key="serilog:write-to:File.path" value="%APPDATA%\MyApp\log.txt" />
+```
+
+### JSON `appsettings.json` configuration
+
+To use the file 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:
+
+```powershell
+Install-Package Serilog.Settings.Configuration
+```
+
+Instead of configuring the file directly in code, call `ReadFrom.Configuration()`:
+
+```csharp
+var configuration = new ConfigurationBuilder()
+    .AddJsonFile("appsettings.json")
+    .Build();
+
+var logger = new LoggerConfiguration()
+    .ReadFrom.Configuration(configuration)
+    .CreateLogger();
 ```
 
-### JSON formatting
+In your `appsettings.json` file, under the `Serilog` node, :
 
-To emit JSON, rather than plain text, a formatter can be specified:
+```json
+{
+  "Serilog": {
+    "WriteTo": [
+      { "Name": "File", "Args": { "path": "log.txt", "rollingInterval": "Day" } }
+    ]
+  }
+}
+```
+
+See the XML `<appSettings>` example above for a discussion of available `Args` options.
+
+### Controlling event formatting
+
+The file sink creates events in a fixed text format by default:
+
+```
+2018-07-06 09:02:17.148 +10:00 [INF] HTTP GET / responded 200 in 1994 ms
+```
+
+The format is controlled using an _output template_, which the file configuration method accepts as an `outputTemplate` parameter.
+
+The default format above corresponds to an output template like:
 
 ```csharp
-    .WriteTo.File(new JsonFormatter(), "log.txt")
+  .WriteTo.File("log.txt",
+    outputTemplate: "{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} [{Level:u3}] {Message:lj}{NewLine}{Exception}")
 ```
 
-To configure an alternative formatter in XML `<appSettings>`, specify the formatter's assembly-qualified type name as the setting `value`.
+##### JSON event formatting
+
+To write events to the file in an alternative format such as [JSON](https://github.com/serilog/serilog-formatting-compact), pass an `ITextFormatter` as the first argument:
+
+```csharp
+    // Install-Package Serilog.Formatting.Compact
+    .WriteTo.File(new CompactJsonFormatter(), "log.txt")
+```
 
 ### Shared log files
 
-Multiple processes can concurrently write to the same log file if the `shared` parameter is set to `true`:
+To enable multi-process shared log files, set `shared` to `true`:
 
 ```csharp
     .WriteTo.File("log.txt", shared: true)
 ```
 
+### Auditing
+
+The file sink can operate as an audit file through `AuditTo`:
+
+```csharp
+    .AuditTo.File("audit.txt")
+```
+
+Only a limited subset of configuration options are currently available in this mode.
+
 ### Performance
 
 By default, the file sink will flush each event written through it to disk. To improve write performance, specifying `buffered: true` will permit the underlying stream to buffer writes.
 
-The [Serilog.Sinks.Async](https://github.com/serilog/serilog-sinks-async) package can be used to wrap the file sink and perform all disk accss on a background worker thread.
+The [Serilog.Sinks.Async](https://github.com/serilog/serilog-sinks-async) package can be used to wrap the file sink and perform all disk access on a background worker thread.
 
 _Copyright &copy; 2016 Serilog Contributors - Provided under the [Apache License, Version 2.0](http://apache.org/licenses/LICENSE-2.0.html)._

appveyor.yml

@@ -1,22 +1,25 @@
 version: '{build}'
 skip_tags: true
-image: Visual Studio 2015
+image:
+  - Visual Studio 2017
+  - Ubuntu
 configuration: Release
-install:
-  - ps: mkdir -Force ".\build\" | Out-Null
-  - ps: Invoke-WebRequest "https://raw.githubusercontent.com/dotnet/cli/rel/1.0.0-preview2/scripts/obtain/dotnet-install.ps1" -OutFile ".\build\installcli.ps1"
-  - ps: $env:DOTNET_INSTALL_DIR = "$pwd\.dotnetcli"
-  - ps: '& .\build\installcli.ps1 -InstallDir "$env:DOTNET_INSTALL_DIR" -NoPath -Version 1.0.0-preview2-003121'
-  - ps: $env:Path = "$env:DOTNET_INSTALL_DIR;$env:Path"
 build_script:
 - ps: ./Build.ps1
+for:
+-
+  matrix:
+    only:
+      - image: Ubuntu
+  build_script:
+    - sh build.sh
 test: off
 artifacts:
 - path: artifacts/Serilog.*.nupkg
 deploy:
 - provider: NuGet
   api_key:
-    secure: nvZ/z+pMS91b3kG4DgfES5AcmwwGoBYQxr9kp4XiJHj25SAlgdIxFx++1N0lFH2x
+    secure: N59tiJECUYpip6tEn0xvdmDAEiP9SIzyLEFLpwiigm/8WhJvBNs13QxzT1/3/JW/
   skip_symbols: true
   on:
     branch: /^(master|dev)$/

build.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+
+set -e 
+dotnet --info
+dotnet --list-sdks
+dotnet restore
+
+echo "🤖 Attempting to build..."
+for path in src/**/*.csproj; do
+    dotnet build -f netstandard1.3 -c Release ${path}
+    dotnet build -f netstandard2.0 -c Release ${path}
+done
+
+echo "🤖 Running tests..."
+for path in test/*.Tests/*.csproj; do
+    dotnet test -f netcoreapp2.0  -c Release ${path}
+done

example/Sample/Program.cs

@@ -11,12 +11,12 @@ public static void Main(string[] args)
         {
             SelfLog.Enable(Console.Out);
 
+            var sw = System.Diagnostics.Stopwatch.StartNew();
+
             Log.Logger = new LoggerConfiguration()
                 .WriteTo.File("log.txt")
                 .CreateLogger();
 
-            var sw = System.Diagnostics.Stopwatch.StartNew();
-
             for (var i = 0; i < 1000000; ++i)
             {
                 Log.Information("Hello, file logger!");