Skip to content

Commit b460d0e

Browse files
nblumhardtnblumhardt
authored
Merge pull request #256 from serilog/dev
9.0.0 Release
2 parents 2138e8c + 92751dd commit b460d0e

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

44 files changed

+1190
-335
lines changed

‎.github/workflows/ci.yml

+41
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# If this file is renamed, the incrementing run attempt number will be reset.
2+
3+
name: CI
4+
5+
on:
6+
push:
7+
branches: [ "dev", "main" ]
8+
pull_request:
9+
branches: [ "dev", "main" ]
10+
11+
env:
12+
CI_BUILD_NUMBER_BASE: ${{ github.run_number }}
13+
CI_TARGET_BRANCH: ${{ github.head_ref || github.ref_name }}
14+
15+
jobs:
16+
build:
17+
18+
# The build must run on Windows so that .NET Framework targets can be built and tested.
19+
runs-on: windows-latest
20+
21+
permissions:
22+
contents: write
23+
24+
steps:
25+
- uses: actions/checkout@v4
26+
- name: Setup
27+
uses: actions/setup-dotnet@v4
28+
with:
29+
dotnet-version: 9.0.x
30+
- name: Compute build number
31+
shell: bash
32+
run: |
33+
echo "CI_BUILD_NUMBER=$(($CI_BUILD_NUMBER_BASE+2300))" >> $GITHUB_ENV
34+
- name: Build and Publish
35+
env:
36+
DOTNET_CLI_TELEMETRY_OPTOUT: true
37+
NUGET_API_KEY: ${{ secrets.NUGET_API_KEY }}
38+
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
39+
shell: pwsh
40+
run: |
41+
./Build.ps1

‎.gitignore

+4-1
Original file line numberDiff line numberDiff line change
@@ -200,4 +200,7 @@ project.lock.json
200200
# JetBrains Rider
201201
.idea
202202

203-
.vscode
203+
.vscode
204+
205+
.DS_Store
206+

‎Build.ps1

+57-36
Original file line numberDiff line numberDiff line change
@@ -1,58 +1,79 @@
1-
echo "build: Build started"
1+
Write-Output "build: Tool versions follow"
22

3-
$env:Path = "$pwd/.dotnetcli;$env:Path"
3+
dotnet --version
4+
dotnet --list-sdks
5+
6+
Write-Output "build: Build started"
47

58
Push-Location $PSScriptRoot
9+
try {
10+
if(Test-Path .\artifacts) {
11+
Write-Output "build: Cleaning ./artifacts"
12+
Remove-Item ./artifacts -Force -Recurse
13+
}
614

7-
if(Test-Path .\artifacts) {
8-
echo "build: Cleaning .\artifacts"
9-
Remove-Item .\artifacts -Force -Recurse
10-
}
15+
& dotnet restore --no-cache
1116

12-
& dotnet restore --no-cache
17+
$dbp = [Xml] (Get-Content .\Directory.Version.props)
18+
$versionPrefix = $dbp.Project.PropertyGroup.VersionPrefix
1319

14-
$branch = @{ $true = $env:APPVEYOR_REPO_BRANCH; $false = $(git symbolic-ref --short -q HEAD) }[$env:APPVEYOR_REPO_BRANCH -ne $NULL];
15-
$revision = @{ $true = "{0:00000}" -f [convert]::ToInt32("0" + $env:APPVEYOR_BUILD_NUMBER, 10); $false = "local" }[$env:APPVEYOR_BUILD_NUMBER -ne $NULL];
16-
$suffix = @{ $true = ""; $false = "$($branch.Substring(0, [math]::Min(10,$branch.Length)))-$revision"}[$branch -eq "main" -and $revision -ne "local"]
20+
Write-Output "build: Package version prefix is $versionPrefix"
1721

18-
echo "build: Version suffix is $suffix"
22+
$branch = @{ $true = $env:CI_TARGET_BRANCH; $false = $(git symbolic-ref --short -q HEAD) }[$NULL -ne $env:CI_TARGET_BRANCH];
23+
$revision = @{ $true = "{0:00000}" -f [convert]::ToInt32("0" + $env:CI_BUILD_NUMBER, 10); $false = "local" }[$NULL -ne $env:CI_BUILD_NUMBER];
24+
$suffix = @{ $true = ""; $false = "$($branch.Substring(0, [math]::Min(10,$branch.Length)) -replace '([^a-zA-Z0-9\-]*)', '')-$revision"}[$branch -eq "main" -and $revision -ne "local"]
25+
$commitHash = $(git rev-parse --short HEAD)
26+
$buildSuffix = @{ $true = "$($suffix)-$($commitHash)"; $false = "$($branch)-$($commitHash)" }[$suffix -ne ""]
1927

20-
foreach ($src in ls src/*) {
21-
Push-Location $src
28+
Write-Output "build: Package version suffix is $suffix"
29+
Write-Output "build: Build version suffix is $buildSuffix"
2230

23-
echo "build: Packaging project in $src"
31+
& dotnet build -c Release --version-suffix=$buildSuffix /p:ContinuousIntegrationBuild=true
32+
if($LASTEXITCODE -ne 0) { throw "Build failed" }
2433

25-
if($suffix) {
26-
& dotnet pack -c Release --include-source -o ..\..\artifacts --version-suffix=$suffix
27-
} else {
28-
& dotnet pack -c Release --include-source -o ..\..\artifacts
29-
}
34+
foreach ($src in Get-ChildItem src/*) {
35+
Push-Location $src
3036

31-
if($LASTEXITCODE -ne 0) { throw "build failed" }
37+
Write-Output "build: Packaging project in $src"
3238

33-
Pop-Location
34-
}
39+
if ($suffix) {
40+
& dotnet pack -c Release --no-build --no-restore -o ../../artifacts --version-suffix=$suffix
41+
} else {
42+
& dotnet pack -c Release --no-build --no-restore -o ../../artifacts
43+
}
44+
if($LASTEXITCODE -ne 0) { throw "Packaging failed" }
45+
46+
Pop-Location
47+
}
3548

36-
foreach ($test in ls test/*.PerformanceTests) {
37-
Push-Location $test
49+
foreach ($test in Get-ChildItem test/*.Tests) {
50+
Push-Location $test
3851

39-
echo "build: Building performance test project in $test"
52+
Write-Output "build: Testing project in $test"
4053

41-
& dotnet build -c Release
42-
if($LASTEXITCODE -ne 0) { throw "test failed" }
54+
& dotnet test -c Release --no-build --no-restore
55+
if($LASTEXITCODE -ne 0) { throw "Testing failed" }
4356

44-
Pop-Location
45-
}
57+
Pop-Location
58+
}
4659

47-
foreach ($test in ls test/*.Tests) {
48-
Push-Location $test
60+
if ($env:NUGET_API_KEY) {
61+
# GitHub Actions will only supply this to branch builds and not PRs. We publish
62+
# builds from any branch this action targets (i.e. main and dev).
4963

50-
echo "build: Testing project in $test"
64+
Write-Output "build: Publishing NuGet packages"
5165

52-
& dotnet test -c Release
53-
if($LASTEXITCODE -ne 0) { throw "test failed" }
66+
foreach ($nupkg in Get-ChildItem artifacts/*.nupkg) {
67+
& dotnet nuget push -k $env:NUGET_API_KEY -s https://api.nuget.org/v3/index.json "$nupkg"
68+
if($LASTEXITCODE -ne 0) { throw "Publishing failed" }
69+
}
5470

71+
if (!($suffix)) {
72+
Write-Output "build: Creating release for version $versionPrefix"
73+
74+
iex "gh release create v$versionPrefix --title v$versionPrefix --generate-notes $(get-item ./artifacts/*.nupkg) $(get-item ./artifacts/*.snupkg)"
75+
}
76+
}
77+
} finally {
5578
Pop-Location
5679
}
57-
58-
Pop-Location

‎Directory.Build.props

+17-4
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,25 @@
11
<Project>
2-
2+
<!-- Properties in this file are expected to be identical for all Serilog organization projects. If
3+
a property value is project-specific, please record it in the CSPROJ file instead. -->
4+
<Import Project="$(MSBuildThisFileDirectory)Directory.Version.props" />
35
<PropertyGroup>
46
<LangVersion>latest</LangVersion>
57
<TreatWarningsAsErrors>True</TreatWarningsAsErrors>
6-
<SignAssembly>true</SignAssembly>
8+
<!-- The condition is required to support BenchmarkDotNet -->
9+
<SignAssembly Condition="Exists('$(MSBuildThisFileDirectory)assets/Serilog.snk')">true</SignAssembly>
710
<AssemblyOriginatorKeyFile>$(MSBuildThisFileDirectory)assets/Serilog.snk</AssemblyOriginatorKeyFile>
8-
<PublicSign Condition=" '$(OS)' != 'Windows_NT' ">true</PublicSign>
11+
<CheckEolTargetFramework>false</CheckEolTargetFramework>
912
<Nullable>enable</Nullable>
13+
<ImplicitUsings>enable</ImplicitUsings>
14+
<GenerateDocumentationFile>true</GenerateDocumentationFile>
15+
<PublishRepositoryUrl>true</PublishRepositoryUrl>
16+
<EmbedUntrackedSources>true</EmbedUntrackedSources>
17+
<IncludeSymbols>true</IncludeSymbols>
18+
<SymbolPackageFormat>snupkg</SymbolPackageFormat>
1019
</PropertyGroup>
11-
20+
<ItemGroup Condition="'$(TargetFrameworkIdentifier)' == '.NETFramework'">
21+
<Reference Include="System" />
22+
<Reference Include="System.Core" />
23+
<Reference Include="Microsoft.CSharp" />
24+
</ItemGroup>
1225
</Project>

‎Directory.Build.targets

-3
This file was deleted.

‎Directory.Version.props

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
<Project>
2+
<PropertyGroup>
3+
<!-- This must match the major and minor components of the referenced Microsoft.Extensions.Logging package. -->
4+
<VersionPrefix>9.0.0</VersionPrefix>
5+
</PropertyGroup>
6+
</Project>

‎README.md

+64-28
Original file line numberDiff line numberDiff line change
@@ -28,41 +28,41 @@ using Serilog;
2828

2929
public class Startup
3030
{
31-
public Startup(IHostingEnvironment env)
32-
{
33-
Log.Logger = new LoggerConfiguration()
34-
.Enrich.FromLogContext()
35-
.WriteTo.Console()
36-
.CreateLogger();
37-
38-
// Other startup code
31+
public Startup(IHostingEnvironment env)
32+
{
33+
Log.Logger = new LoggerConfiguration()
34+
.Enrich.FromLogContext()
35+
.WriteTo.Console()
36+
.CreateLogger();
37+
38+
// Other startup code
3939
```
4040

4141
**Finally, for .NET Core 2.0+**, in your `Startup` class's `Configure()` method, remove the existing logger configuration entries and
4242
call `AddSerilog()` on the provided `loggingBuilder`.
4343

4444
```csharp
45-
public void ConfigureServices(IServiceCollection services)
46-
{
47-
services.AddLogging(loggingBuilder =>
48-
loggingBuilder.AddSerilog(dispose: true));
45+
public void ConfigureServices(IServiceCollection services)
46+
{
47+
services.AddLogging(loggingBuilder =>
48+
loggingBuilder.AddSerilog(dispose: true));
4949

50-
// Other services ...
51-
}
50+
// Other services ...
51+
}
5252
```
5353

5454
**For .NET Core 1.0 or 1.1**, in your `Startup` class's `Configure()` method, remove the existing logger configuration entries and call `AddSerilog()` on the provided `loggerFactory`.
5555

5656
```
57-
public void Configure(IApplicationBuilder app,
58-
IHostingEnvironment env,
59-
ILoggerFactory loggerfactory,
60-
IApplicationLifetime appLifetime)
61-
{
62-
loggerfactory.AddSerilog();
63-
64-
// Ensure any buffered events are sent at shutdown
65-
appLifetime.ApplicationStopped.Register(Log.CloseAndFlush);
57+
public void Configure(IApplicationBuilder app,
58+
IHostingEnvironment env,
59+
ILoggerFactory loggerfactory,
60+
IApplicationLifetime appLifetime)
61+
{
62+
loggerfactory.AddSerilog();
63+
64+
// Ensure any buffered events are sent at shutdown
65+
appLifetime.ApplicationStopped.Register(Log.CloseAndFlush);
6666
```
6767

6868
That's it! With the level bumped up a little you should see log output like:
@@ -80,6 +80,19 @@ That's it! With the level bumped up a little you should see log output like:
8080
[22:14:45.741 DBG] Handled. Status code: 304 File: /css/site.css
8181
```
8282

83+
### Including the log category in text-format sink output
84+
All _Microsoft.Extensions.Logging.ILogger_ implementations are created with a specified [_log category_](https://learn.microsoft.com/en-us/dotnet/core/extensions/logging?tabs=command-line#log-category) string, which is then attached as structured data to each log message created by that `ILogger` instance. Typically, the log category is the fully-qualified name of the class generating the log messages. This convention is implemented by the [`ILogger<TCategoryName>`](https://learn.microsoft.com/en-us/dotnet/api/microsoft.extensions.logging.ilogger-1) interface, which is commonly used as an injected dependency in frameworks that use _Microsoft.Extensions.Logging_.
85+
86+
_Serilog.Extensions.Logging_ captures the `ILogger`'s log category, but it's not included in the default output templates for text-based sinks, such as [Console](https://github.com/serilog/serilog-sinks-console), [File](https://github.com/serilog/serilog-sinks-file) and [Debug](https://github.com/serilog/serilog-sinks-debug).
87+
88+
To include the log category in the final written messages, add the `{SourceContext}` named hole to a customised `outputTemplate` parameter value when configuring the relevant sink(s). For example:
89+
```csharp
90+
.WriteTo.Console(
91+
outputTemplate: "[{Timestamp:HH:mm:ss} {Level:u3}] {SourceContext}: {Message:lj}{NewLine}{Exception}")
92+
.WriteTo.File("log.txt",
93+
outputTemplate: "{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} [{Level:u3}] {SourceContext}: {Message:lj}{NewLine}{Exception}")
94+
```
95+
8396
### Notes on Log Scopes
8497

8598
_Microsoft.Extensions.Logging_ provides the `BeginScope` API, which can be used to add arbitrary properties to log events within a certain region of code. The API comes in two forms:
@@ -90,7 +103,8 @@ _Microsoft.Extensions.Logging_ provides the `BeginScope` API, which can be used
90103
Using the extension method will add a `Scope` property to your log events. This is most useful for adding simple "scope strings" to your events, as in the following code:
91104

92105
```csharp
93-
using (_logger.BeginScope("Transaction")) {
106+
using (_logger.BeginScope("Transaction"))
107+
{
94108
_logger.LogInformation("Beginning...");
95109
_logger.LogInformation("Completed in {DurationMs}ms...", 30);
96110
}
@@ -102,8 +116,9 @@ using (_logger.BeginScope("Transaction")) {
102116
If you simply want to add a "bag" of additional properties to your log events, however, this extension method approach can be overly verbose. For example, to add `TransactionId` and `ResponseJson` properties to your log events, you would have to do something like the following:
103117

104118
```csharp
105-
// WRONG! Prefer the dictionary approach below instead
106-
using (_logger.BeginScope("TransactionId: {TransactionId}, ResponseJson: {ResponseJson}", 12345, jsonString)) {
119+
// WRONG! Prefer the dictionary or value tuple approach below instead
120+
using (_logger.BeginScope("TransactionId: {TransactionId}, ResponseJson: {ResponseJson}", 12345, jsonString))
121+
{
107122
_logger.LogInformation("Completed in {DurationMs}ms...", 30);
108123
}
109124
// Example JSON output:
@@ -125,11 +140,13 @@ Moreover, the template string within `BeginScope` is rather arbitrary when all y
125140
A far better alternative is to use the `BeginScope<TState>(TState state)` method. If you provide any `IEnumerable<KeyValuePair<string, object>>` to this method, then Serilog will output the key/value pairs as structured properties _without_ the `Scope` property, as in this example:
126141

127142
```csharp
128-
var scopeProps = new Dictionary<string, object> {
143+
var scopeProps = new Dictionary<string, object>
144+
{
129145
{ "TransactionId", 12345 },
130146
{ "ResponseJson", jsonString },
131147
};
132-
using (_logger.BeginScope(scopeProps) {
148+
using (_logger.BeginScope(scopeProps)
149+
{
133150
_logger.LogInformation("Transaction completed in {DurationMs}ms...", 30);
134151
}
135152
// Example JSON output:
@@ -144,6 +161,25 @@ using (_logger.BeginScope(scopeProps) {
144161
// }
145162
```
146163

164+
Alternatively provide a `ValueTuple<string, object?>` to this method, where `Item1` is the property name and `Item2` is the property value.
165+
Note that `T2` _must_ be `object?` if your target platform is net462 or netstandard2.0.
166+
167+
```csharp
168+
using (_logger.BeginScope(("TransactionId", 12345))
169+
{
170+
_logger.LogInformation("Transaction completed in {DurationMs}ms...", 30);
171+
}
172+
// Example JSON output:
173+
// {
174+
// "@t":"2020-10-29T19:05:56.4176816Z",
175+
// "@m":"Completed in 30ms...",
176+
// "@i":"51812baa",
177+
// "DurationMs":30,
178+
// "SourceContext":"SomeNamespace.SomeService",
179+
// "TransactionId": 12345
180+
// }
181+
```
182+
147183
### Versioning
148184

149185
This package tracks the versioning and target framework support of its [_Microsoft.Extensions.Logging_](https://nuget.org/packages/Microsoft.Extensions.Logging) dependency.

‎Setup.ps1

-9
This file was deleted.

‎appveyor.yml

-26
This file was deleted.

0 commit comments

Comments
 (0)