Several requested features have been added which provide more control over correlation ID generation and customisation.
This release includes several breaking changes, and upgrading will require some changes to consuming code.
A major new feature in this release is the concept of an ICorrelationIdProvider
. This interface defines an abstraction for generating correlation IDs. The library includes two provider implementations which include the previous behaviour. The GuidCorrelationIdProvider
, when registered will generate new GUID-based correlations IDs. The TraceIdCorrelationIdProvider
will generate the correlation ID, setting it to the same value as the TraceIdentifier string on the HttpContext
.
Only one provider may be registered. Registering multiple providers will cause an InvalidOperationException
to be thrown.
BREAKING CHANGES
Registering services
Changes have been made to the registration methods on the IServiceCollection
to support the new providers concept.
When registering the required correlation ID services by calling the AddCorrelationId
method, this now returns an ICorrelationIdBuilder
that supports additional methods that can be used to configure the provider, which will be used. This method does not set a default provider, so it is expected that one of the appropriate ICorrelationIdBuilder
builder methods be called.
Alternatively, the AddCorrelationId<T>
method can be called, which accepts the type to use for the ICorrelationIdProvider
.
Finally, the AddDefaultCorrelationId
method may be used, which returns the IServiceCollection
and which does not support further configuration of the correlation ID configuration using the builder. In this case, the default provider will be the GuidCorrelationIdProvider
. This method exists for those wanting to chain IServiceCollection
extension methods and where the default GUID provider is suitable.
Configuration Options
A change has been made to how the CorrelationIdOptions
are configured for the correlation ID behaviour. Previously, a CorrelationIdOptions
instance could be passed to the UseCorrelationId
extension method on the IApplicationBuilder
. This is no longer the correct way to register options. Instead, options can be configured via Action delegate overloads on the IServiceCollection
extensions methods.
services.AddDefaultCorrelationId(options =>
{
options.CorrelationIdGenerator = () => "Foo";
options.AddToLoggingScope = true;
options.EnforceHeader = true;
options.IgnoreRequestHeader = false;
options.IncludeInResponse = true;
options.RequestHeader = "My-Custom-Correlation-Id";
options.ResponseHeader = "X-Correlation-Id";
options.UpdateTraceIdentifier = false;
});
CorrelationIdOptions
WARNING: BREAKING CHANGES
DefaultHeader
renamed toRequestHeader
UseGuidForCorrelationId
removed as this is now controlled by the registeredICorrelationIdProvider
.
New Options
- Added
ResponseHeader
- The name of the header to which the Correlation ID is written. This change supports scenarios where it is necessary to read from one header but return the correlation ID using a different header name. Defaults to the same value as theRequestHeader
unless specifically set. - Added
IgnoreRequestHeader
- Whentrue
the incoming correlation ID in theRequestHeader
is ignored and a new correlation ID is generated. - Added
EnforceHeader
- Enforces the inclusion of the correlation ID request header. Whentrue
and a correlation ID header is not included, the request will fail with a 400 Bad Request response. - Added
AddToLoggingScope
- Add the correlation ID value to the logger scope for all requests. Whentrue
the value of the correlation ID will be added to the logger scope payload. - Added
LoggingScopeKey
- The name for the key used when adding the correlation ID to the logger scope. Defaults to 'CorrelationId' - Added
CorrelationIdGenerator
- AFunc<string>
that returns the correlation ID in cases where no correlation ID is retrieved from the request header. It can be used to customise the correlation ID generation. When set, this function will be used instead of the registeredICorrelationIdProvider
.
CorrelationContext
The constructor for this type has been made public (previously internal) to support the creation of CorrelationContext
instances when unit testing code which depends on the ICorrelationContextAccessor
. This makes mocking the ICorrelationContextAccessor
a much easier task.
IApplicationBuilder Extension Methods
The overloads of the UseCorrelationId
methods have been removed as options are no longer provided when adding the correlation ID middleware to the pipeline.
UseCorrelationId(string header)
removed.UseCorrelationId(CorrelationIdOptions options)
removed.