Skip to content

Commit 5ac8460

Browse files
authored
.Net Processes - Add Process-Level Error Handler (#9477)
### Motivation and Context <!-- Thank you for your contribution to the semantic-kernel repo! Please help reviewers and future users, providing the following information: 1. Why is this change required? 2. What problem does it solve? 3. What scenario does it contribute to? 4. If it fixes an open issue, please link to the issue here. --> Enabled support for function-specific error-handler step in this PR: #9187 Fixes: #9291 This change provides the ability to define a _process scoped_ error handler (as opposed to function specific). When a function-scoped error-handler is defined, it will take precedence. ### Description <!-- Describe your changes, the overall approach, the underlying design. These notes will help understanding how your code works. Thanks! --> ```c# ProcessBuilder process = new(nameof(ProcessFunctionErrorHandledAsync)); ProcessStepBuilder errorStep = process.AddStepFromType<ErrorStep>(); process.OnError().SendEventTo(new ProcessFunctionTargetBuilder(errorStep)); class ErrorStep : KernelProcessStep { [KernelFunction] public void GlobalErrorHandler(Exception exception) { } } ``` **Notes:** - Switch error handler from passing `Exception` object to a `KernelProcessError` to satisfy serialization expectations - Normalized namespaces for `Internal` shared code - Introduced shared `ProcessConstants` file - Opportunistically converted some `List` creation to `Array` - Opportunistically included parameter name in some `Verify` assertions. - Opportunistically removed a extraneous _not-null_ directives (`!`) - Verified DAPR error handling in demo app (`True` means the expected error handler was invoked): <img width="449" alt="image" src="https://github.com/user-attachments/assets/2d987378-edd2-4c9f-92dd-cf112888b8b0"> ### Contribution Checklist <!-- Before submitting this PR, please make sure: --> - [X] The code builds clean without any errors or warnings - [X] The PR follows the [SK Contribution Guidelines](https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md) and the [pre-submission formatting script](https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md#development-scripts) raises no violations - [X] All unit tests pass, and I have added new tests where possible - [X] I didn't break anyone 😄
1 parent 303c202 commit 5ac8460

30 files changed

Lines changed: 395 additions & 105 deletions

‎dotnet/samples/Demos/ProcessWithDapr/Controllers/ProcessController.cs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ public ProcessController(Kernel kernel)
3232
public async Task<IActionResult> PostAsync(string processId)
3333
{
3434
var process = this.GetProcess();
35-
var processContext = await process.StartAsync(this._kernel, new KernelProcessEvent() { Id = CommonEvents.StartProcess }, processId: processId);
35+
var processContext = await process.StartAsync(new KernelProcessEvent() { Id = CommonEvents.StartProcess }, processId: processId);
3636
var finalState = await processContext.GetStateAsync();
3737

3838
return this.Ok(processId);

‎dotnet/samples/GettingStartedWithProcesses/Step04/Steps/RenderMessageStep.cs‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -41,11 +41,11 @@ public void RenderDone()
4141
/// Render exception
4242
/// </summary>
4343
[KernelFunction]
44-
public void RenderError(Exception exception, ILogger logger)
44+
public void RenderError(KernelProcessError error, ILogger logger)
4545
{
46-
string message = string.IsNullOrWhiteSpace(exception.Message) ? "Unexpected failure" : exception.Message;
47-
Render($"ERROR: {message} [{exception.GetType().Name}]{Environment.NewLine}{exception.StackTrace}");
48-
logger.LogError(exception, "Unexpected failure.");
46+
string message = string.IsNullOrWhiteSpace(error.Message) ? "Unexpected failure" : error.Message;
47+
Render($"ERROR: {message} [{error.GetType().Name}]{Environment.NewLine}{error.StackTrace}");
48+
logger.LogError("Unexpected failure: {ErrorMessage} [{ErrorType}]", error.Message, error.Type);
4949
}
5050

5151
/// <summary>
Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
// Copyright (c) Microsoft. All rights reserved.
2+
using System;
3+
using System.Runtime.Serialization;
4+
5+
namespace Microsoft.SemanticKernel;
6+
7+
/// <summary>
8+
/// Represents an failure that occurred during the execution of a process.
9+
/// </summary>
10+
/// <remarks>
11+
/// Initializes a new instance of the <see cref="KernelProcessError"/> class.
12+
/// </remarks>
13+
/// <param name="Type">The exception type name</param>
14+
/// <param name="Message">The exception message (<see cref="Exception.Message"/></param>
15+
/// <param name="StackTrace">The exception stack-trace (<see cref="Exception.StackTrace"/></param>
16+
[DataContract]
17+
public sealed record KernelProcessError(
18+
[property:DataMember]
19+
string Type,
20+
[property:DataMember]
21+
string Message,
22+
[property:DataMember]
23+
string? StackTrace)
24+
{
25+
/// <summary>
26+
/// The inner failure, when exists, as <see cref="KernelProcessError"/>.
27+
/// </summary>
28+
[DataMember]
29+
public KernelProcessError? InnerError { get; init; }
30+
31+
/// <summary>
32+
/// Factory method to create a <see cref="KernelProcessError"/> from a source <see cref="Exception"/> object.
33+
/// </summary>
34+
public static KernelProcessError FromException(Exception ex) =>
35+
new(ex.GetType().Name, ex.Message, ex.StackTrace)
36+
{
37+
InnerError = ex.InnerException is not null ? FromException(ex.InnerException) : null
38+
};
39+
}

‎dotnet/src/Experimental/Process.Abstractions/KernelProcessStepInfo.cs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
using System;
44
using System.Collections.Generic;
55
using System.Linq;
6-
using Microsoft.SemanticKernel.Process;
6+
using Microsoft.SemanticKernel.Process.Internal;
77
using Microsoft.SemanticKernel.Process.Models;
88

99
namespace Microsoft.SemanticKernel;
Lines changed: 3 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
// Copyright (c) Microsoft. All rights reserved.
22

33
using System.Collections.Generic;
4+
using Microsoft.SemanticKernel.Process.Internal;
45
using Microsoft.SemanticKernel.Process.Models;
56

67
namespace Microsoft.SemanticKernel;
@@ -10,18 +11,6 @@ namespace Microsoft.SemanticKernel;
1011
/// </summary>
1112
internal sealed class EndStep : ProcessStepBuilder
1213
{
13-
private const string EndStepValue = "Microsoft.SemanticKernel.Process.EndStep";
14-
15-
/// <summary>
16-
/// The name of the end step.
17-
/// </summary>
18-
public const string EndStepName = EndStepValue;
19-
20-
/// <summary>
21-
/// The event ID for stopping a process.
22-
/// </summary>
23-
public const string EndStepId = EndStepValue;
24-
2514
/// <summary>
2615
/// The static instance of the <see cref="EndStep"/> class.
2716
/// </summary>
@@ -31,7 +20,7 @@ internal sealed class EndStep : ProcessStepBuilder
3120
/// Represents the end of a process.
3221
/// </summary>
3322
internal EndStep()
34-
: base(EndStepName)
23+
: base(ProcessConstants.EndStepName)
3524
{
3625
}
3726

@@ -49,6 +38,6 @@ internal override KernelProcessStepInfo BuildStep()
4938
internal override KernelProcessStepInfo BuildStep(KernelProcessStepStateMetadata<object>? stateMetadata)
5039
{
5140
// The end step has no state.
52-
return new KernelProcessStepInfo(typeof(KernelProcessStepState), new KernelProcessStepState(EndStepName), []);
41+
return new KernelProcessStepInfo(typeof(KernelProcessStepState), new KernelProcessStepState(ProcessConstants.EndStepName), []);
5342
}
5443
}

‎dotnet/src/Experimental/Process.Core/ProcessBuilder.cs‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
using System;
44
using System.Collections.Generic;
55
using System.Linq;
6+
using Microsoft.SemanticKernel.Process.Internal;
67
using Microsoft.SemanticKernel.Process.Models;
78

89
namespace Microsoft.SemanticKernel;
@@ -177,6 +178,19 @@ public ProcessEdgeBuilder OnInputEvent(string eventId)
177178
return new ProcessEdgeBuilder(this, eventId);
178179
}
179180

181+
/// <summary>
182+
/// Provides an instance of <see cref="ProcessStepEdgeBuilder"/> for defining an edge to a
183+
/// step that responds to an unhandled process error.
184+
/// </summary>
185+
/// <returns>An instance of <see cref="ProcessStepEdgeBuilder"/></returns>
186+
/// <remarks>
187+
/// To target a specific error source, use the <see cref="ProcessStepBuilder.OnFunctionError"/> on the step.
188+
/// </remarks>
189+
public ProcessEdgeBuilder OnError()
190+
{
191+
return new ProcessEdgeBuilder(this, ProcessConstants.GlobalErrorEventId);
192+
}
193+
180194
/// <summary>
181195
/// Retrieves the target for a given external event. The step associated with the target is the process itself (this).
182196
/// </summary>

‎dotnet/src/Experimental/Process.Core/ProcessStepBuilder.cs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
using System.Collections.Generic;
55
using System.Linq;
66
using System.Text.Json;
7-
using Microsoft.SemanticKernel.Process;
7+
using Microsoft.SemanticKernel.Process.Internal;
88
using Microsoft.SemanticKernel.Process.Models;
99

1010
namespace Microsoft.SemanticKernel;

‎dotnet/src/Experimental/Process.Core/ProcessStepEdgeBuilder.cs‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
// Copyright (c) Microsoft. All rights reserved.
22

33
using System;
4+
using Microsoft.SemanticKernel.Process.Internal;
45

56
namespace Microsoft.SemanticKernel;
67

@@ -76,6 +77,6 @@ public void StopProcess()
7677

7778
var outputTarget = new ProcessFunctionTargetBuilder(EndStep.Instance);
7879
this.Target = outputTarget;
79-
this.Source.LinkTo(EndStep.EndStepName, this);
80+
this.Source.LinkTo(ProcessConstants.EndStepName, this);
8081
}
8182
}

‎dotnet/src/Experimental/Process.LocalRuntime/LocalProcess.cs‎

Lines changed: 21 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -8,14 +8,14 @@
88
using System.Threading.Tasks;
99
using Microsoft.Extensions.Logging;
1010
using Microsoft.Extensions.Logging.Abstractions;
11+
using Microsoft.SemanticKernel.Process.Internal;
1112
using Microsoft.SemanticKernel.Process.Runtime;
1213
using Microsoft.VisualStudio.Threading;
1314

1415
namespace Microsoft.SemanticKernel;
1516

1617
internal sealed class LocalProcess : LocalStep, IDisposable
1718
{
18-
private const string EndProcessId = "Microsoft.SemanticKernel.Process.EndStep";
1919
private readonly JoinableTaskFactory _joinableTaskFactory;
2020
private readonly JoinableTaskContext _joinableTaskContext;
2121
private readonly Channel<KernelProcessEvent> _externalEventChannel;
@@ -240,11 +240,11 @@ private async Task Internal_ExecuteAsync(Kernel? kernel = null, int maxSuperstep
240240
}
241241

242242
// Complete the writing side, indicating no more messages in this superstep.
243-
var messagesToProcess = messageChannel.ToList();
243+
var messagesToProcess = messageChannel.ToArray();
244244
messageChannel.Clear();
245245

246246
// If there are no messages to process, wait for an external event.
247-
if (messagesToProcess.Count == 0)
247+
if (messagesToProcess.Length == 0)
248248
{
249249
if (!keepAlive || !await this._externalEventChannel.Reader.WaitToReadAsync(cancellationToken).ConfigureAwait(false))
250250
{
@@ -257,7 +257,7 @@ private async Task Internal_ExecuteAsync(Kernel? kernel = null, int maxSuperstep
257257
foreach (var message in messagesToProcess)
258258
{
259259
// Check for end condition
260-
if (message.DestinationId.Equals(EndProcessId, StringComparison.OrdinalIgnoreCase))
260+
if (message.DestinationId.Equals(ProcessConstants.EndStepName, StringComparison.OrdinalIgnoreCase))
261261
{
262262
this._processCancelSource?.Cancel();
263263
break;
@@ -320,7 +320,7 @@ private void EnqueueExternalMessages(Queue<ProcessMessage> messageChannel)
320320
private void EnqueueStepMessages(LocalStep step, Queue<ProcessMessage> messageChannel)
321321
{
322322
var allStepEvents = step.GetAllEvents();
323-
foreach (var stepEvent in allStepEvents)
323+
foreach (ProcessEvent stepEvent in allStepEvents)
324324
{
325325
// Emit the event out of the process (this one) if it's visibility is public.
326326
if (stepEvent.Visibility == KernelProcessEventVisibility.Public)
@@ -329,10 +329,25 @@ private void EnqueueStepMessages(LocalStep step, Queue<ProcessMessage> messageCh
329329
}
330330

331331
// Get the edges for the event and queue up the messages to be sent to the next steps.
332-
foreach (var edge in step.GetEdgeForEvent(stepEvent.Id!))
332+
bool foundEdge = false;
333+
foreach (KernelProcessEdge edge in step.GetEdgeForEvent(stepEvent.Id))
333334
{
334335
ProcessMessage message = ProcessMessageFactory.CreateFromEdge(edge, stepEvent.Data);
335336
messageChannel.Enqueue(message);
337+
foundEdge = true;
338+
}
339+
340+
// Error event was raised with no edge to handle it, send it to an edge defined as the global error target.
341+
if (!foundEdge && stepEvent.IsError)
342+
{
343+
if (this._outputEdges.TryGetValue(ProcessConstants.GlobalErrorEventId, out List<KernelProcessEdge>? edges))
344+
{
345+
foreach (KernelProcessEdge edge in edges)
346+
{
347+
ProcessMessage message = ProcessMessageFactory.CreateFromEdge(edge, stepEvent.Data);
348+
messageChannel.Enqueue(message);
349+
}
350+
}
336351
}
337352
}
338353
}

‎dotnet/src/Experimental/Process.LocalRuntime/LocalStep.cs‎

Lines changed: 28 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@
88
using Microsoft.Extensions.DependencyInjection;
99
using Microsoft.Extensions.Logging;
1010
using Microsoft.Extensions.Logging.Abstractions;
11+
using Microsoft.SemanticKernel.Process.Internal;
1112
using Microsoft.SemanticKernel.Process.Runtime;
1213

1314
namespace Microsoft.SemanticKernel;
@@ -111,9 +112,17 @@ internal IEnumerable<KernelProcessEdge> GetEdgeForEvent(string eventId)
111112
/// </summary>
112113
/// <param name="processEvent">The event to emit.</param>
113114
/// <returns>A <see cref="ValueTask"/></returns>
114-
public ValueTask EmitEventAsync(KernelProcessEvent processEvent)
115+
public ValueTask EmitEventAsync(KernelProcessEvent processEvent) => this.EmitEventAsync(processEvent, isError: false);
116+
117+
/// <summary>
118+
/// Emits an event from the step.
119+
/// </summary>
120+
/// <param name="processEvent">The event to emit.</param>
121+
/// <param name="isError">Flag indicating if the event being emitted is in response to a step failure</param>
122+
/// <returns>A <see cref="ValueTask"/></returns>
123+
internal ValueTask EmitEventAsync(KernelProcessEvent processEvent, bool isError)
115124
{
116-
this.EmitEvent(ProcessEvent.FromKernelProcessEvent(processEvent, this._eventNamespace));
125+
this.EmitEvent(new ProcessEvent(this._eventNamespace, processEvent, isError));
117126
return default;
118127
}
119128

@@ -148,7 +157,7 @@ internal virtual async Task HandleMessageAsync(ProcessMessage message)
148157

149158
if (!this._inputs.TryGetValue(message.FunctionName, out Dictionary<string, object?>? functionParameters))
150159
{
151-
this._inputs[message.FunctionName] = new();
160+
this._inputs[message.FunctionName] = [];
152161
functionParameters = this._inputs[message.FunctionName];
153162
}
154163

@@ -179,28 +188,31 @@ internal virtual async Task HandleMessageAsync(ProcessMessage message)
179188
throw new ArgumentException($"Function {targetFunction} not found in plugin {this.Name}");
180189
}
181190

182-
FunctionResult? invokeResult = null;
183-
string? eventName = null;
184-
object? eventValue = null;
185-
186191
// Invoke the function, catching all exceptions that it may throw, and then post the appropriate event.
187192
#pragma warning disable CA1031 // Do not catch general exception types
188193
try
189194
{
190-
invokeResult = await this.InvokeFunction(function, this._kernel, arguments).ConfigureAwait(false);
191-
eventName = $"{targetFunction}.OnResult";
192-
eventValue = invokeResult?.GetValue<object>();
195+
FunctionResult invokeResult = await this.InvokeFunction(function, this._kernel, arguments).ConfigureAwait(false);
196+
await this.EmitEventAsync(
197+
new KernelProcessEvent
198+
{
199+
Id = $"{targetFunction}.OnResult",
200+
Data = invokeResult.GetValue<object>(),
201+
}).ConfigureAwait(false);
193202
}
194203
catch (Exception ex)
195204
{
196205
this._logger.LogError("Error in Step {StepName}: {ErrorMessage}", this.Name, ex.Message);
197-
eventName = $"{targetFunction}.OnError";
198-
eventValue = ex;
206+
await this.EmitEventAsync(
207+
new KernelProcessEvent
208+
{
209+
Id = $"{targetFunction}.OnError",
210+
Data = KernelProcessError.FromException(ex),
211+
},
212+
isError: true).ConfigureAwait(false);
199213
}
200214
finally
201215
{
202-
await this.EmitEventAsync(new KernelProcessEvent { Id = eventName, Data = eventValue }).ConfigureAwait(false);
203-
204216
// Reset the inputs for the function that was just executed
205217
this._inputs[targetFunction] = new(this._initialInputs[targetFunction] ?? []);
206218
}
@@ -216,7 +228,7 @@ protected virtual async ValueTask InitializeStepAsync()
216228
{
217229
// Instantiate an instance of the inner step object
218230
KernelProcessStep stepInstance = (KernelProcessStep)ActivatorUtilities.CreateInstance(this._kernel.Services, this._stepInfo.InnerStepType);
219-
var kernelPlugin = KernelPluginFactory.CreateFromObject(stepInstance, pluginName: this._stepInfo.State.Name!);
231+
var kernelPlugin = KernelPluginFactory.CreateFromObject(stepInstance, pluginName: this._stepInfo.State.Name);
220232

221233
// Load the kernel functions
222234
foreach (KernelFunction f in kernelPlugin)
@@ -312,6 +324,6 @@ protected ProcessEvent ScopedEvent(ProcessEvent localEvent)
312324
protected ProcessEvent ScopedEvent(KernelProcessEvent processEvent)
313325
{
314326
Verify.NotNull(processEvent, nameof(processEvent));
315-
return ProcessEvent.FromKernelProcessEvent(processEvent, $"{this.Name}_{this.Id}");
327+
return new ProcessEvent($"{this.Name}_{this.Id}", processEvent);
316328
}
317329
}

0 commit comments

Comments
 (0)