Skip to content

Commit 13a33d0

Browse files
author
vp
committed
feat: Enhance pipeline feature with detailed XML documentation and public access modifiers
1 parent 1cdb9d5 commit 13a33d0

5 files changed

Lines changed: 191 additions & 15 deletions

File tree

‎src/Common.Utilities/Pipeline/Behaviors/PipelineBehaviorInvoker.cs‎

Lines changed: 30 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,13 +5,32 @@
55

66
namespace BridgingIT.DevKit.Common;
77

8-
internal interface IPipelineBehaviorInvoker
8+
/// <summary>
9+
/// Invokes pipeline behaviors through a non-generic runtime contract.
10+
/// </summary>
11+
public interface IPipelineBehaviorInvoker
912
{
13+
/// <summary>
14+
/// Executes behavior logic around the full pipeline invocation.
15+
/// </summary>
16+
/// <param name="context">The current pipeline context.</param>
17+
/// <param name="next">The inner pipeline delegate.</param>
18+
/// <param name="cancellationToken">The cancellation token for the execution.</param>
19+
/// <returns>The final pipeline result returned by the inner delegate.</returns>
1020
ValueTask<Result> ExecuteAsync(
1121
PipelineContextBase context,
1222
Func<ValueTask<Result>> next,
1323
CancellationToken cancellationToken);
1424

25+
/// <summary>
26+
/// Executes behavior logic around one pipeline step invocation.
27+
/// </summary>
28+
/// <param name="context">The current pipeline context.</param>
29+
/// <param name="step">The step definition being executed.</param>
30+
/// <param name="result">The carried pipeline result before the step runs.</param>
31+
/// <param name="next">The inner step delegate.</param>
32+
/// <param name="cancellationToken">The cancellation token for the execution.</param>
33+
/// <returns>The <see cref="PipelineControl"/> returned by the inner step delegate.</returns>
1534
ValueTask<PipelineControl> ExecuteStepAsync(
1635
PipelineContextBase context,
1736
IPipelineStepDefinition step,
@@ -20,8 +39,17 @@ ValueTask<PipelineControl> ExecuteStepAsync(
2039
CancellationToken cancellationToken);
2140
}
2241

23-
internal static class PipelineBehaviorInvoker
42+
/// <summary>
43+
/// Creates runtime invokers for typed pipeline behaviors.
44+
/// </summary>
45+
public static class PipelineBehaviorInvoker
2446
{
47+
/// <summary>
48+
/// Creates an <see cref="IPipelineBehaviorInvoker"/> for the specified typed behavior instance.
49+
/// </summary>
50+
/// <param name="behavior">The typed pipeline behavior instance.</param>
51+
/// <param name="contextType">The pipeline context type handled by the behavior.</param>
52+
/// <returns>A runtime adapter for the specified behavior.</returns>
2553
public static IPipelineBehaviorInvoker Create(object behavior, Type contextType)
2654
{
2755
ArgumentNullException.ThrowIfNull(behavior);

‎src/Common.Utilities/Pipeline/Constants.cs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ namespace BridgingIT.DevKit.Common;
88
/// <summary>
99
/// Provides constants used by the pipeline feature.
1010
/// </summary>
11-
internal static class Constants
11+
public static class Constants
1212
{
1313
/// <summary>
1414
/// Gets the structured log key used by internal pipeline logging.

‎src/Common.Utilities/Pipeline/Context/PipelineContextTypeResolver.cs‎

Lines changed: 27 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,16 @@
55

66
namespace BridgingIT.DevKit.Common;
77

8-
internal static class PipelineContextTypeResolver
8+
/// <summary>
9+
/// Resolves and validates pipeline context types for steps, hooks, and behaviors.
10+
/// </summary>
11+
public static class PipelineContextTypeResolver
912
{
13+
/// <summary>
14+
/// Infers the pipeline context type handled by a pipeline step type.
15+
/// </summary>
16+
/// <param name="stepType">The pipeline step type to inspect.</param>
17+
/// <returns>The inferred pipeline context type.</returns>
1018
public static Type InferStepContextType(Type stepType)
1119
{
1220
ArgumentNullException.ThrowIfNull(stepType);
@@ -18,24 +26,40 @@ public static Type InferStepContextType(Type stepType)
1826
$"Pipeline step '{stepType.PrettyName()}' must derive from '{typeof(PipelineStep<>).PrettyName()}' or '{typeof(AsyncPipelineStep<>).PrettyName()}'.");
1927
}
2028

29+
/// <summary>
30+
/// Infers the pipeline context type handled by a pipeline hook type.
31+
/// </summary>
32+
/// <param name="hookType">The pipeline hook type to inspect.</param>
33+
/// <returns>The inferred pipeline context type.</returns>
2134
public static Type InferHookContextType(Type hookType)
2235
{
2336
ArgumentNullException.ThrowIfNull(hookType);
2437

2538
return FindClosedGenericInterfaceArgument(hookType, typeof(IPipelineHook<>))
2639
?? throw new PipelineDefinitionValidationException(
27-
$"Pipeline hook '{hookType.PrettyName()}' must implement '{typeof(IPipelineHook<>).PrettyName()}'.");
40+
$"Pipeline hook '{hookType.PrettyName()}' must implement '{typeof(IPipelineHook<>).PrettyName()}'.");
2841
}
2942

43+
/// <summary>
44+
/// Infers the pipeline context type handled by a pipeline behavior type.
45+
/// </summary>
46+
/// <param name="behaviorType">The pipeline behavior type to inspect.</param>
47+
/// <returns>The inferred pipeline context type.</returns>
3048
public static Type InferBehaviorContextType(Type behaviorType)
3149
{
3250
ArgumentNullException.ThrowIfNull(behaviorType);
3351

3452
return FindClosedGenericInterfaceArgument(behaviorType, typeof(IPipelineBehavior<>))
3553
?? throw new PipelineDefinitionValidationException(
36-
$"Pipeline behavior '{behaviorType.PrettyName()}' must implement '{typeof(IPipelineBehavior<>).PrettyName()}'.");
54+
$"Pipeline behavior '{behaviorType.PrettyName()}' must implement '{typeof(IPipelineBehavior<>).PrettyName()}'.");
3755
}
3856

57+
/// <summary>
58+
/// Determines whether a component context type is compatible with a pipeline context type.
59+
/// </summary>
60+
/// <param name="pipelineContextType">The pipeline context type.</param>
61+
/// <param name="componentContextType">The component context type.</param>
62+
/// <returns><see langword="true"/> when the component can run for the pipeline context; otherwise, <see langword="false"/>.</returns>
3963
public static bool IsCompatible(Type pipelineContextType, Type componentContextType)
4064
{
4165
ArgumentNullException.ThrowIfNull(pipelineContextType);

‎src/Common.Utilities/Pipeline/Hooks/PipelineHookInvoker.cs‎

Lines changed: 44 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,21 +5,63 @@
55

66
namespace BridgingIT.DevKit.Common;
77

8-
internal interface IPipelineHookInvoker
8+
/// <summary>
9+
/// Invokes pipeline hooks through a non-generic runtime contract.
10+
/// </summary>
11+
public interface IPipelineHookInvoker
912
{
13+
/// <summary>
14+
/// Invokes the hook callback before the pipeline starts processing steps.
15+
/// </summary>
16+
/// <param name="context">The current pipeline context.</param>
17+
/// <param name="cancellationToken">The cancellation token for the execution.</param>
1018
ValueTask OnPipelineStartingAsync(PipelineContextBase context, CancellationToken cancellationToken);
1119

20+
/// <summary>
21+
/// Invokes the hook callback before an individual step attempt starts.
22+
/// </summary>
23+
/// <param name="context">The current pipeline context.</param>
24+
/// <param name="step">The step definition being executed.</param>
25+
/// <param name="cancellationToken">The cancellation token for the execution.</param>
1226
ValueTask OnStepStartingAsync(PipelineContextBase context, IPipelineStepDefinition step, CancellationToken cancellationToken);
1327

28+
/// <summary>
29+
/// Invokes the hook callback after an individual step attempt completes.
30+
/// </summary>
31+
/// <param name="context">The current pipeline context.</param>
32+
/// <param name="step">The step definition that completed.</param>
33+
/// <param name="control">The control outcome returned by the step execution.</param>
34+
/// <param name="cancellationToken">The cancellation token for the execution.</param>
1435
ValueTask OnStepCompletedAsync(PipelineContextBase context, IPipelineStepDefinition step, PipelineControl control, CancellationToken cancellationToken);
1536

37+
/// <summary>
38+
/// Invokes the hook callback when the pipeline completes successfully.
39+
/// </summary>
40+
/// <param name="context">The current pipeline context.</param>
41+
/// <param name="result">The final pipeline result.</param>
42+
/// <param name="cancellationToken">The cancellation token for the execution.</param>
1643
ValueTask OnPipelineCompletedAsync(PipelineContextBase context, Result result, CancellationToken cancellationToken);
1744

45+
/// <summary>
46+
/// Invokes the hook callback when the pipeline completes with a failed result.
47+
/// </summary>
48+
/// <param name="context">The current pipeline context.</param>
49+
/// <param name="result">The final failed pipeline result.</param>
50+
/// <param name="cancellationToken">The cancellation token for the execution.</param>
1851
ValueTask OnPipelineFailedAsync(PipelineContextBase context, Result result, CancellationToken cancellationToken);
1952
}
2053

21-
internal static class PipelineHookInvoker
54+
/// <summary>
55+
/// Creates runtime invokers for typed pipeline hooks.
56+
/// </summary>
57+
public static class PipelineHookInvoker
2258
{
59+
/// <summary>
60+
/// Creates an <see cref="IPipelineHookInvoker"/> for the specified typed hook instance.
61+
/// </summary>
62+
/// <param name="hook">The typed pipeline hook instance.</param>
63+
/// <param name="contextType">The pipeline context type handled by the hook.</param>
64+
/// <returns>A runtime adapter for the specified hook.</returns>
2365
public static IPipelineHookInvoker Create(object hook, Type contextType)
2466
{
2567
ArgumentNullException.ThrowIfNull(hook);

‎src/Common.Utilities/Pipeline/PipelineTypedLogger.cs‎

Lines changed: 89 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,19 @@ namespace BridgingIT.DevKit.Common;
77

88
using Microsoft.Extensions.Logging;
99

10-
internal static partial class PipelineTypedLogger
10+
/// <summary>
11+
/// Provides source-generated logging helpers for pipeline execution events.
12+
/// </summary>
13+
public static partial class PipelineTypedLogger
1114
{
15+
/// <summary>
16+
/// Logs that a pipeline execution has started.
17+
/// </summary>
18+
/// <param name="logger">The logger to write to.</param>
19+
/// <param name="logKey">The structured log key.</param>
20+
/// <param name="pipelineName">The pipeline name.</param>
21+
/// <param name="executionId">The pipeline execution identifier.</param>
22+
/// <param name="correlationId">The correlation identifier for the execution.</param>
1223
[LoggerMessage(
1324
EventId = 1,
1425
Level = LogLevel.Debug,
@@ -20,6 +31,15 @@ public static partial void LogPipelineStarted(
2031
Guid executionId,
2132
string correlationId);
2233

34+
/// <summary>
35+
/// Logs that a pipeline execution has finished.
36+
/// </summary>
37+
/// <param name="logger">The logger to write to.</param>
38+
/// <param name="logKey">The structured log key.</param>
39+
/// <param name="pipelineName">The pipeline name.</param>
40+
/// <param name="executionId">The pipeline execution identifier.</param>
41+
/// <param name="status">The final execution status.</param>
42+
/// <param name="durationMs">The elapsed duration in milliseconds.</param>
2343
[LoggerMessage(
2444
EventId = 2,
2545
Level = LogLevel.Debug,
@@ -32,21 +52,39 @@ public static partial void LogPipelineFinished(
3252
PipelineExecutionStatus status,
3353
double durationMs);
3454

55+
/// <summary>
56+
/// Logs that a pipeline step has started.
57+
/// </summary>
58+
/// <param name="logger">The logger to write to.</param>
59+
/// <param name="logKey">The structured log key.</param>
60+
/// <param name="pipelineName">The pipeline name.</param>
61+
/// <param name="stepName">The step name.</param>
62+
/// <param name="executionId">The pipeline execution identifier.</param>
3563
[LoggerMessage(
3664
EventId = 3,
3765
Level = LogLevel.Debug,
38-
Message = "[{LogKey}] step started (pipeline={PipelineName}, step={StepName}, executionId={ExecutionId})")]
66+
Message = "[{LogKey}] pipeline step started (pipeline={PipelineName}, step={StepName}, executionId={ExecutionId})")]
3967
public static partial void LogStepStarted(
4068
ILogger logger,
4169
string logKey,
4270
string pipelineName,
4371
string stepName,
4472
Guid executionId);
4573

74+
/// <summary>
75+
/// Logs that a pipeline step has finished.
76+
/// </summary>
77+
/// <param name="logger">The logger to write to.</param>
78+
/// <param name="logKey">The structured log key.</param>
79+
/// <param name="pipelineName">The pipeline name.</param>
80+
/// <param name="stepName">The step name.</param>
81+
/// <param name="executionId">The pipeline execution identifier.</param>
82+
/// <param name="outcome">The final step outcome.</param>
83+
/// <param name="durationMs">The elapsed duration in milliseconds.</param>
4684
[LoggerMessage(
4785
EventId = 4,
4886
Level = LogLevel.Debug,
49-
Message = "[{LogKey}] step finished (pipeline={PipelineName}, step={StepName}, executionId={ExecutionId}, outcome={Outcome}) -> took {DurationMs}ms")]
87+
Message = "[{LogKey}] pipeline step finished (pipeline={PipelineName}, step={StepName}, executionId={ExecutionId}, outcome={Outcome}) -> took {DurationMs}ms")]
5088
public static partial void LogStepFinished(
5189
ILogger logger,
5290
string logKey,
@@ -56,10 +94,21 @@ public static partial void LogStepFinished(
5694
PipelineControlOutcome outcome,
5795
double durationMs);
5896

97+
/// <summary>
98+
/// Logs that a pipeline step requested a retry.
99+
/// </summary>
100+
/// <param name="logger">The logger to write to.</param>
101+
/// <param name="logKey">The structured log key.</param>
102+
/// <param name="pipelineName">The pipeline name.</param>
103+
/// <param name="stepName">The step name.</param>
104+
/// <param name="executionId">The pipeline execution identifier.</param>
105+
/// <param name="attempt">The current attempt number.</param>
106+
/// <param name="maxAttempts">The configured maximum number of attempts.</param>
107+
/// <param name="message">The retry reason.</param>
59108
[LoggerMessage(
60109
EventId = 5,
61110
Level = LogLevel.Warning,
62-
Message = "[{LogKey}] step retry requested (pipeline={PipelineName}, step={StepName}, executionId={ExecutionId}, attempt={Attempt}, maxAttempts={MaxAttempts}, message={Message})")]
111+
Message = "[{LogKey}] pipeline step retry requested (pipeline={PipelineName}, step={StepName}, executionId={ExecutionId}, attempt={Attempt}, maxAttempts={MaxAttempts}, message={Message})")]
63112
public static partial void LogStepRetrying(
64113
ILogger logger,
65114
string logKey,
@@ -70,10 +119,19 @@ public static partial void LogStepRetrying(
70119
int maxAttempts,
71120
string message);
72121

122+
/// <summary>
123+
/// Logs that a pipeline step threw an exception.
124+
/// </summary>
125+
/// <param name="logger">The logger to write to.</param>
126+
/// <param name="logKey">The structured log key.</param>
127+
/// <param name="pipelineName">The pipeline name.</param>
128+
/// <param name="stepName">The step name.</param>
129+
/// <param name="executionId">The pipeline execution identifier.</param>
130+
/// <param name="exception">The exception that was thrown.</param>
73131
[LoggerMessage(
74132
EventId = 6,
75133
Level = LogLevel.Error,
76-
Message = "[{LogKey}] step exception (pipeline={PipelineName}, step={StepName}, executionId={ExecutionId})")]
134+
Message = "[{LogKey}] pipeline step failure (pipeline={PipelineName}, step={StepName}, executionId={ExecutionId})")]
77135
public static partial void LogStepException(
78136
ILogger logger,
79137
string logKey,
@@ -82,6 +140,14 @@ public static partial void LogStepException(
82140
Guid executionId,
83141
Exception exception);
84142

143+
/// <summary>
144+
/// Logs that the pipeline execution threw an exception.
145+
/// </summary>
146+
/// <param name="logger">The logger to write to.</param>
147+
/// <param name="logKey">The structured log key.</param>
148+
/// <param name="pipelineName">The pipeline name.</param>
149+
/// <param name="executionId">The pipeline execution identifier.</param>
150+
/// <param name="exception">The exception that was thrown.</param>
85151
[LoggerMessage(
86152
EventId = 7,
87153
Level = LogLevel.Error,
@@ -93,21 +159,37 @@ public static partial void LogPipelineException(
93159
Guid executionId,
94160
Exception exception);
95161

162+
/// <summary>
163+
/// Logs that a pipeline hook threw an exception that was ignored.
164+
/// </summary>
165+
/// <param name="logger">The logger to write to.</param>
166+
/// <param name="logKey">The structured log key.</param>
167+
/// <param name="pipelineName">The pipeline name.</param>
168+
/// <param name="executionId">The pipeline execution identifier.</param>
169+
/// <param name="exception">The exception that was ignored.</param>
96170
[LoggerMessage(
97171
EventId = 8,
98172
Level = LogLevel.Warning,
99-
Message = "[{LogKey}] hook failure ignored (pipeline={PipelineName}, executionId={ExecutionId})")]
173+
Message = "[{LogKey}] pipeline hook failure ignored (pipeline={PipelineName}, executionId={ExecutionId})")]
100174
public static partial void LogHookFailure(
101175
ILogger logger,
102176
string logKey,
103177
string pipelineName,
104178
Guid executionId,
105179
Exception exception);
106180

181+
/// <summary>
182+
/// Logs that a pipeline completion callback failed.
183+
/// </summary>
184+
/// <param name="logger">The logger to write to.</param>
185+
/// <param name="logKey">The structured log key.</param>
186+
/// <param name="pipelineName">The pipeline name.</param>
187+
/// <param name="executionId">The pipeline execution identifier.</param>
188+
/// <param name="exception">The exception that was thrown by the callback.</param>
107189
[LoggerMessage(
108190
EventId = 9,
109191
Level = LogLevel.Error,
110-
Message = "[{LogKey}] completion callback failed (pipeline={PipelineName}, executionId={ExecutionId})")]
192+
Message = "[{LogKey}] pipeline completion callback failed (pipeline={PipelineName}, executionId={ExecutionId})")]
111193
public static partial void LogCompletionCallbackFailed(
112194
ILogger logger,
113195
string logKey,

0 commit comments

Comments
 (0)