NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
NuGet · #1439 most downloaded on NuGet
ASP.NET Core correlation ID middleware for distributed microservices.
Last release 5 years ago
no release in 18 months
Ships unpredictably
gaps range from 8 days to 117.4 years
Nearly every release is documented
notes for 6 of 6 stable releases
1 version withdrawn
withdrawn after publishing
127 years old
10 releases · first in 1900
Do not throw an exception when Correlation accessor has Context as null [ #96 ]
This release includes several breaking changes, and upgrading will require some changes to consuming code.
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
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.
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;
});
WARNING: BREAKING CHANGES
DefaultHeader renamed to RequestHeaderUseGuidForCorrelationId removed as this is now controlled by the registered ICorrelationIdProvider.New Options
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 the RequestHeader unless specifically set.IgnoreRequestHeader - When true the incoming correlation ID in the RequestHeader is ignored and a new correlation ID is generated.EnforceHeader - Enforces the inclusion of the correlation ID request header. When true and a correlation ID header is not included, the request will fail with a 400 Bad Request response.AddToLoggingScope - Add the correlation ID value to the logger scope for all requests. When true the value of the correlation ID will be added to the logger scope payload.LoggingScopeKey - The name for the key used when adding the correlation ID to the logger scope. Defaults to 'CorrelationId'CorrelationIdGenerator - A Func<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 registered ICorrelationIdProvider.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.
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.One column per quarter.
Unfortunately, despite this being a minor release a potential breaking change has slipped in. The Create method on the CorrelationContextFactory requi…
Adds two additional options that can be set when adding the Correlation ID middleware:
UpdateTraceIdentifier - Controls whether the ASP.NET Core TraceIdentifier will be set to match the CorrelationId. The default value is true.
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.
Adds an additional property Header to the CorrelationContext so that the currently configured header name can be retrieved easily to then be set on downstream requests.
POTENTIAL BREAKING CHANGE:
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.
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.
Adds a new option UpdateTraceIdentifier : Controls whether the ASP.NET Core TraceIdentifier will be set to match the CorrelationId. The default value is true .
Adds a new option UseGuidForCorrelationId : Controls whether a GUID will be used in cases where no correlation ID is retrieved from the request header. The default value is false .
Nothing published for this version
Nothing published for this version
Nothing published for this version
Non breaking change to include the correct project and repo URLs in the NuGet package information.
Non breaking change to include the correct project and repo URLs in the NuGet package information.
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…
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.
In order to use the 2.0.0 version of this library, the IServiceCollection extension 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();
}
Fixes a bug where an ArgumentException may be thrown if a response header already exists when trying to add it via the middleware - See https://github
Bug Fixes:
A small bug fix release.
Fixes:
Issue #3 - Ensure that we don't try to set the response header if it already set which would result in an ArgumentException being thrown.
This site is open source. Improve this page .
This site is open source. Improve this page .
Your coding agent can read these notes before it upgrades. Set up the MCP server →