diff --git a/docs/preview/03-Features/correlation.md b/docs/preview/03-Features/correlation.md index dc27d089..b3b5e262 100644 --- a/docs/preview/03-Features/correlation.md +++ b/docs/preview/03-Features/correlation.md @@ -106,116 +106,4 @@ namespace Application } } } -``` - -## Configuration - -The library also provides a way configure some correlation specific options that you can later retrieve during get/set of the correlation information in your application. - -```csharp -public void ConfigureServices(IServiceCollection services) -{ - services.AddCorrelation(options => - { - // Configuration on the transaction ID (`X-Transaction-ID`) request/response header. - // --------------------------------------------------------------------------------- - - // Whether the transaction ID can be specified in the request, and will be used throughout the request handling. - // The request will return early when the `.AllowInRequest` is set to `false` and the request does contain the header (default: true). - options.Transaction.AllowInRequest = true; - - // Whether or not the transaction ID should be generated when there isn't any transaction ID found in the request. - // When the `.GenerateWhenNotSpecified` is set to `false` and the request doesn't contain the header, no value will be available for the transaction ID; - // otherwise a GUID will be generated (default: true). - options.Transaction.GenerateWhenNotSpecified = true; - - // Whether to include the transaction ID in the response (default: true). - options.Transaction.IncludeInResponse = true; - - // The header to look for in the request, and will be set in the response (default: X-Transaction-ID). - options.Transaction.HeaderName = "X-Transaction-ID"; - - // The function that will generate the transaction ID, when the `.GenerateWhenNotSpecified` is set to `false` and the request doesn't contain the header. - // (default: new `Guid`). - options.Transaction.GenerateId = () => $"Transaction-{Guid.NewGuid()}"; - - // Configuration on the operation ID (`RequestId`) response header. - // ---------------------------------------------------------------- - - // Whether to include the operation ID in the response (default: true). - options.Operation.IncludeInResponse = true; - - // The header that will contain the operation ID in the response (default: RequestId). - options.Operation.HeaderName = "RequestId"; - - // The function that will generate the operation ID header value. - // (default: new `Guid`). - options.Operation.GenerateId = () => $"Operation-{Guid.NewGuid()}"; - - // Configuration on the operation parent ID. - // ----------------------------------------- - - // Whether to extract the operation parent ID from the request or not (default: true). - options.OperationParent.ExtractFromRequest = false; - - // The header that will contain the full operation parent ID (default: Request-Id). - options.OperationParent.OperationParentHeaderName = "Request-Id"; - - // The function that will generate the operation parent ID when it shouldn't be extracted from the request. - options.OperationParent.GenerateId = () => $"Parent-{Guid.newGuid()}"; - }); -} -``` - -Later in the application, the options can be retrieved by injecting the `IOptions` type. - -### Custom Configuration - -We also provide a way to provide custom configuration options when the application uses a custom correlation model. - -For example, with a custom correlation model: - -```csharp -using Arcus.Observability.Correlation; - -namespace Application -{ - public class OrderCorrelationInfo : CorrelationInfo - { - public string OrderId { get; } - } -} -``` - -We could introduce an `OrderCorrelationInfoOptions` model: - -```csharp -using Arcus.Observability.Correlation; - -namespace Application -{ - public class OrderCorrelationInfoOptions : CorrelationInfoOptions - { - public bool IncludeOrderId { get; set; } - } -} -``` - -This custom options model can then be included when registering the correlation: - -```csharp -using Microsoft.Extensions.DependencyInjection; - -namespace Application -{ - public class Startup - { - public void ConfigureServices(IServiceCollection services) - { - services.AddCorrelation(options => options.IncludeOrderId = true); - } - } -} -``` - - +``` \ No newline at end of file diff --git a/src/Arcus.Observability.Correlation/CorrelationInfoOperationOptions.cs b/src/Arcus.Observability.Correlation/CorrelationInfoOperationOptions.cs index 346c06e0..5beb9d31 100644 --- a/src/Arcus.Observability.Correlation/CorrelationInfoOperationOptions.cs +++ b/src/Arcus.Observability.Correlation/CorrelationInfoOperationOptions.cs @@ -6,6 +6,7 @@ namespace Arcus.Observability.Correlation /// /// Correlation options specific for the operation ID. /// + [Obsolete("Use HTTP, messaging, or custom-specific correlation options instead")] public class CorrelationInfoOperationOptions { private string _headerName = "RequestId"; diff --git a/src/Arcus.Observability.Correlation/CorrelationInfoOptions.cs b/src/Arcus.Observability.Correlation/CorrelationInfoOptions.cs index 76c2f2a2..c9516c52 100644 --- a/src/Arcus.Observability.Correlation/CorrelationInfoOptions.cs +++ b/src/Arcus.Observability.Correlation/CorrelationInfoOptions.cs @@ -1,8 +1,11 @@ -namespace Arcus.Observability.Correlation +using System; + +namespace Arcus.Observability.Correlation { /// /// Options for handling correlation id on incoming requests. /// + [Obsolete("Use HTTP, messaging, or custom-specific correlation options instead")] public class CorrelationInfoOptions { /// diff --git a/src/Arcus.Observability.Correlation/CorrelationInfoTransactionOptions.cs b/src/Arcus.Observability.Correlation/CorrelationInfoTransactionOptions.cs index b570683a..c656fbc8 100644 --- a/src/Arcus.Observability.Correlation/CorrelationInfoTransactionOptions.cs +++ b/src/Arcus.Observability.Correlation/CorrelationInfoTransactionOptions.cs @@ -6,6 +6,7 @@ namespace Arcus.Observability.Correlation /// /// Correlation options specific to the transaction ID. /// + [Obsolete("Use HTTP, messaging, or custom-specific correlation options instead")] public class CorrelationInfoTransactionOptions { private string _headerName = "X-Transaction-ID"; diff --git a/src/Arcus.Observability.Correlation/CorrelationInfoUpstreamServiceOptions.cs b/src/Arcus.Observability.Correlation/CorrelationInfoUpstreamServiceOptions.cs index c17033f5..8b17a612 100644 --- a/src/Arcus.Observability.Correlation/CorrelationInfoUpstreamServiceOptions.cs +++ b/src/Arcus.Observability.Correlation/CorrelationInfoUpstreamServiceOptions.cs @@ -6,6 +6,7 @@ namespace Arcus.Observability.Correlation /// /// Correlation options specific to the upstream services, used in the . /// + [Obsolete("Use HTTP, messaging, or custom-specific correlation options instead")] public class CorrelationInfoUpstreamServiceOptions { private string _operationParentIdHeaderName = "Request-Id"; @@ -44,4 +45,4 @@ public Func GenerateId } } } -} \ No newline at end of file +} diff --git a/src/Arcus.Observability.Correlation/IServiceCollectionExtensions.cs b/src/Arcus.Observability.Correlation/IServiceCollectionExtensions.cs index 6ab901e4..06a5dc00 100644 --- a/src/Arcus.Observability.Correlation/IServiceCollectionExtensions.cs +++ b/src/Arcus.Observability.Correlation/IServiceCollectionExtensions.cs @@ -11,29 +11,60 @@ namespace Microsoft.Extensions.DependencyInjection // ReSharper disable once InconsistentNaming public static class IServiceCollectionExtensions { + /// + /// Adds operation and transaction correlation to the application using the + /// + /// The services collection containing the dependency injection services. + /// Thrown when the is null. + public static IServiceCollection AddCorrelation(this IServiceCollection services) + { + Guard.NotNull(services, nameof(services), "Requires a service collection to register the default correlation accessor to the application services"); + + return AddCorrelation(services); + } + /// /// Adds operation and transaction correlation to the application using the /// /// The services collection containing the dependency injection services. /// The function to configure additional options how the correlation works. + [Obsolete("Use HTTP, messaging, or custom-specific correlation registration instead")] public static IServiceCollection AddCorrelation( this IServiceCollection services, - Action configureOptions = null) + Action configureOptions) { Guard.NotNull(services, nameof(services)); return AddCorrelation(services, new DefaultCorrelationInfoAccessor(), configureOptions); } + /// + /// Adds operation and transaction correlation to the application using the + /// + /// The type of the model. + /// The services collection containing the dependency injection services. + /// Thrown when the is null. + public static IServiceCollection AddCorrelation( + this IServiceCollection services) + where TCorrelationInfo : CorrelationInfo + { + Guard.NotNull(services, nameof(services), "Requires a service collection to register the default correlation accessor to the application services"); + + return AddCorrelation, TCorrelationInfo>( + services, + provider => new DefaultCorrelationInfoAccessor()); + } + /// /// Adds operation and transaction correlation to the application using the /// /// The type of the model. /// The services collection containing the dependency injection services. /// The function to configure additional options how the correlation works. + [Obsolete("Use HTTP, messaging, or custom-specific correlation registration instead")] public static IServiceCollection AddCorrelation( this IServiceCollection services, - Action configureOptions = null) + Action configureOptions) where TCorrelationInfo : CorrelationInfo { Guard.NotNull(services, nameof(services)); @@ -48,6 +79,7 @@ public static IServiceCollection AddCorrelation( /// The type of the custom model. /// The services collection containing the dependency injection services. /// The function to configure additional options how the correlation works. + [Obsolete("Use HTTP, messaging, or custom-specific correlation registration instead")] public static IServiceCollection AddCorrelation( this IServiceCollection services, Action configureOptions = null) @@ -69,6 +101,7 @@ public static IServiceCollection AddCorrelation( /// The services collection containing the dependency injection services. /// The custom implementation to retrieve the . /// The function to configure additional options how the correlation works. + [Obsolete("Use HTTP, messaging, or custom-specific correlation registration instead")] public static IServiceCollection AddCorrelation( this IServiceCollection services, TAccessor customCorrelationAccessor, @@ -81,6 +114,24 @@ public static IServiceCollection AddCorrelation( return AddCorrelation(services, serviceProvider => customCorrelationAccessor, configureOptions); } + /// + /// Adds operation and transaction correlation to the application. + /// + /// The type of the implementation. + /// The services collection containing the dependency injection services. + /// The custom implementation factory to retrieve the . + /// Thrown when the or the is null. + public static IServiceCollection AddCorrelation( + this IServiceCollection services, + Func createCustomCorrelationAccessor) + where TAccessor : class, ICorrelationInfoAccessor + { + Guard.NotNull(services, nameof(services), "Requires a service collection to register the custom correlation accessor to the application services"); + Guard.NotNull(createCustomCorrelationAccessor, nameof(createCustomCorrelationAccessor), "Requires a factory function to create a custom correlation accessor"); + + return AddCorrelation(services, createCustomCorrelationAccessor); + } + /// /// Adds operation and transaction correlation to the application. /// @@ -88,10 +139,11 @@ public static IServiceCollection AddCorrelation( /// The services collection containing the dependency injection services. /// The custom implementation factory to retrieve the . /// The function to configure additional options how the correlation works. + [Obsolete("Use HTTP, messaging, or custom-specific correlation registration instead")] public static IServiceCollection AddCorrelation( this IServiceCollection services, Func createCustomCorrelationAccessor, - Action configureOptions = null) + Action configureOptions) where TAccessor : class, ICorrelationInfoAccessor { Guard.NotNull(services, nameof(services)); @@ -100,6 +152,33 @@ public static IServiceCollection AddCorrelation( return AddCorrelation(services, createCustomCorrelationAccessor, configureOptions); } + /// + /// Adds operation and transaction correlation to the application. + /// + /// The type of the implementation. + /// The type of the custom model. + /// The services collection containing the dependency injection services. + /// The custom implementation factory to retrieve the . + /// Thrown when the or the is null. + public static IServiceCollection AddCorrelation( + this IServiceCollection services, + Func createCustomCorrelationAccessor) + where TAccessor : class, ICorrelationInfoAccessor + where TCorrelationInfo : CorrelationInfo + { + Guard.NotNull(services, nameof(services), "Requires a service collection to register the custom correlation accessor to the application services"); + Guard.NotNull(createCustomCorrelationAccessor, nameof(createCustomCorrelationAccessor), "Requires a factory function to create a custom correlation accessor"); + + services.AddScoped>(createCustomCorrelationAccessor); + services.AddScoped(serviceProvider => + { + return new CorrelationInfoAccessorProxy( + serviceProvider.GetRequiredService>()); + }); + + return services; + } + /// /// Adds operation and transaction correlation to the application. /// @@ -108,10 +187,11 @@ public static IServiceCollection AddCorrelation( /// The services collection containing the dependency injection services. /// The custom implementation factory to retrieve the . /// The function to configure additional options how the correlation works. + [Obsolete("Use HTTP, messaging, or custom-specific correlation registration instead")] public static IServiceCollection AddCorrelation( this IServiceCollection services, Func createCustomCorrelationAccessor, - Action configureOptions = null) + Action configureOptions) where TAccessor : class, ICorrelationInfoAccessor where TCorrelationInfo : CorrelationInfo { @@ -130,12 +210,13 @@ public static IServiceCollection AddCorrelation( /// The services collection containing the dependency injection services. /// The custom implementation factory to retrieve the . /// The function to configure additional options how the correlation works. + [Obsolete("Use HTTP, messaging, or custom-specific correlation registration instead")] public static IServiceCollection AddCorrelation( this IServiceCollection services, Func createCustomCorrelationAccessor, - Action configureOptions = null) + Action configureOptions) where TAccessor : class, ICorrelationInfoAccessor - where TCorrelationInfo : CorrelationInfo + where TCorrelationInfo : CorrelationInfo where TOptions : CorrelationInfoOptions { Guard.NotNull(services, nameof(services)); @@ -148,12 +229,9 @@ public static IServiceCollection AddCorrelation>()); }); - if (configureOptions != null) - { - services.Configure(configureOptions); - } + services.Configure(options => configureOptions?.Invoke(options)); return services; } } -} \ No newline at end of file +}