https://github.com/wdolek/w4k-aspnetcore-correlator
Correlator, ASP.NET middleware for handling correlation/request ID.
https://github.com/wdolek/w4k-aspnetcore-correlator
correlation forwarding-correlation
Last synced: 5 months ago
JSON representation
Correlator, ASP.NET middleware for handling correlation/request ID.
- Host: GitHub
- URL: https://github.com/wdolek/w4k-aspnetcore-correlator
- Owner: wdolek
- License: mit
- Created: 2018-10-18T20:36:05.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2025-11-17T22:07:16.000Z (7 months ago)
- Last Synced: 2025-11-17T23:26:01.486Z (7 months ago)
- Topics: correlation, forwarding-correlation
- Language: C#
- Homepage:
- Size: 382 KB
- Stars: 4
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# W4k.AspNetCore.Correlator
[](https://www.nuget.org/packages/W4k.AspNetCore.Correlator/)
Correlator helps you with handling correlation ID (also "request ID"): reading, generating new one and forwarding
to subsequent requests.
Correlation ID is sent within HTTP headers. If header is not set, Correlator will happily generate new one for you.
Apart from accepting or generating correlation ID, it is also possible to return correlation ID back to caller,
so in case when correlation ID is generated, caller is aware of that value.
To forward correlation ID to subsequent request, it is necessary to use designated HTTP message handler, see
examples below.
## W3 Trace Context and .NET
Be aware that [Trace Context](https://www.w3.org/TR/trace-context/) is **not supported**,
Correlator helps you with simple non-standard headers.
Distributed tracing and trace context is built in .NET, You can get more insights from article:
[.NET distributed tracing](https://learn.microsoft.com/en-us/dotnet/core/diagnostics/distributed-tracing).
## Basic usage
### Startup class
```csharp
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDefaultCorrelator();
var app = builder.Build();
// register as first middleware
// (or as soon as possible to benefit from having correlation ID)
app.UseCorrelator();
// ...
app.Run();
```
### Accessing correlation ID
Correlation ID of current request is available via `ICorrelationContextAccessor.CorrelationContext`:
```csharp
using W4k.AspNetCore.Correlator;
using W4k.AspNetCore.Correlator.Context;
public class MyLittleService
{
private readonly ICorrelationContextAccessor _contextAccessor;
public MyLittleService(ICorrelationContextAccessor contextAccessor)
{
_contextAccessor = contextAccessor;
}
public async Task DoMagicalStuff()
{
CorrelationId correlationId = _contextAccessor.CorrelationContext.CorrelationId;
// ...
}
}
```
## Forwarding correlation ID
In order to pass correlation ID to subsequent requests, additional HTTP message handler has to be registered.
Add `CorrelatorHttpMessageHandler` to HTTP client's message handler pipeline like this:
```csharp
// named HTTP client
builder.Services
.AddHttpClient("DummyClient")
.WithCorrelation();
// typed HTTP client
builder.Services
.AddHttpClient()
.WithCorrelation();
// registering HTTP message handler manually
builder.Services
.AddHttpClient("FizzClient")
.AddHttpMessageHandler();
// registering HTTP client with custom settings
// (global options - CorrelatorOptions.Forward - won't be used)
builder.Services
.AddHttpClient()
.WithCorrelation(PropagationSettings.PropagateAs("X-Legacy-Correlation-Id"));
// ...
```
See "[Configure the HttpMessageHandler](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/http-requests?view=aspnetcore-2.1#configure-the-httpmessagehandler)" for more details about usage of HTTP message handler.
## Validation of correlation ID
It is possible to validate correlation ID value and prevent invalid value to spread. By default, validation is
turned off. In order to turn validation on, implementation of `ICorrelationValidator` has to be registered.
Correlator is shipped with lightweight validator, `CorrelationValueLengthValidator`, which decides whether received
value is valid simply based on its length.
```csharp
builder.Services
.AddDefaultCorrelator()
.WithValidator(new CorrelationValueLengthValidator(64));
```
## Documentation
- [Detailed configuration](docs/configuration.md) description
- [Dependency injection](docs/registration.md) registration
- [Components](docs/components.md) description
- [Alternative packages and further reading](docs/alternatives.md)
---
Icon made by [Kiranshastry](https://www.flaticon.com/authors/kiranshastry) from [Flaticon, www.flaticon.com](https://www.flaticon.com/)