v2.x (Previous)

Provides basic middleware for syncing a TraceIdentity (correlation ID) across ASP.NET Core APIs.

Installation

First install the package via NuGet: Install-Package CorrelationId

In order to use the 2.0.0 version of this library, the IServiceCollection extension method will need to be called in ConfigureServices:

public void ConfigureServices(IServiceCollection services)
{
   services.AddMvc();
   services.AddCorrelationId();
}

The middleware then needs to be added in the Configure method, prior to registering calling UseMvc and any other middleware that you want to have access to the correct CorrelationId. Usually it can be one of the first items registered.

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
   app.UseCorrelationId();

   if (env.IsDevelopment())
   {
	  app.UseDeveloperExceptionPage();
   }

   app.UseMvc();
}

Any calls to your application passing a CorrelationID header will then result in the TraceIdentifier being updated to match the provided ID.

By default CorrelationId looks for a header named "X-Correlation-ID". This is configurable (see below).

Once registered, all default MVC logging will use the updated TraceIdenfier.

To access the CorrelationId from your application code (for custom logging) you can use the newly added CorrelationContext which carries the CorrelationId for the current request. To gain access to the CorrelationContext from your classes you can add a constructor dependency on ICorrelationContextAccessor which will be injected by the DI framework.

You can then use the ICorrelationContextAccessor to access the CorrelationContext and its current ID.

public class TransientClass
{
   private readonly ICorrelationContextAccessor _correlationContext;

   public TransientClass(ICorrelationContextAccessor correlationContext)
   {
	  _correlationContext = correlationContext;
   }

   public string GetCorrelationFromScoped => _correlationContext.CorrelationContext.CorrelationId;
}

Passing on the correlation ID

When your code calls another service you will need to get the correlation ID from the CorrelationContext.CorrelationId property and pass it as a header in your HTTP call. As long as both services are configured with the same header name and both have the Correlation ID middleware enabled, you will see all logging using a matching value between services.

Configuration

If you want to customise the options for the CorrelationId; then you may register the middleware, passing in a CorrelationIdOptions.

Options available in 2.0 and higher:

1. Header - The name of the header from which the Correlation ID is read/written. The default value is X-Correlation-ID.
2. IncludeInResponse - Controls whether the correlation ID is returned in the response headers. The default value is true.

Options available in 2.1 and higher:

3. UpdateTraceIdentifier - Controls whether the ASP.NET Core TraceIdentifier will be set to match the CorrelationId. The default value is true.
4. UseGuidForCorrelationId - Controls whether a GUID will be used in cases where no correlation ID is retrieved from the request header. When false the TraceIdentifier for the current request will be used. The default value is false.

Example of registration with options:

app.UseCorrelationId(new CorrelationIdOptions { 
	Header = "a-different-header", 
	UseGuidForCorrelationId = true 
});