CorrelationId

Release Notes

Packages are available on NuGet: CorrelationId.

v3.0.1

Bug Fixes

v3.0.0

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

BREAKING CHANGES

New Options

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.

2.1.0

Potential breaking changes

Unfortunately, despite this being a minor release, a potential breaking change has slipped in. The Create method on the CorrelationContextFactory requires two arguments (previously one). If you are mocking or using this class directly, then this change may affect you.

2.0.1

2.0.0

Includes breaking changes

This major release introduces a key requirement of including a CorrelationContext which makes it possible to access the CorrelationId in classes that don’t automatically have access to the HttpContext in order to retrieve the TraceIdentifier.

This is a breaking change since the registration of services in now required. An exception will be thrown if the services are not registered prior to calling the middleware.

Consuming classes can now include a constructor dependency for ICorrelationContextAccessor which will enable the retrieval and use of the current CorrelationContext when performing logging.

v1.0.1

v1.0.0