Skip to content

Commit 10818c5

Browse files
authored
.Net: SK Process Cloud Events - Publish Interface abstractions scaffolding (#10222)
### Motivation and Context Initial change need for Cloud Event support, in particular the publishing events scenario. - Initial changes need in abstractions layer - min changes for Dapr Runtime - min changes for Local Runtime - UTs in Local and Dapr Runtime to ensure parity Coming up changes in separate PRs: - New abstractions to be used when creating sk ProcessBuilder - Additional internal plumbing needed - Samples/Demos with usage Fixes #9721 ### Description <!-- Describe your changes, the overall approach, the underlying design. These notes will help understanding how your code works. Thanks! --> ### 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 9655254 commit 10818c5

25 files changed

Lines changed: 493 additions & 18 deletions
Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
// Copyright (c) Microsoft. All rights reserved.
2+
3+
using System.Threading.Tasks;
4+
5+
namespace Microsoft.SemanticKernel;
6+
7+
/// <summary>
8+
/// An interface that provides a channel for emitting external messages from a step.
9+
/// In addition provide common methods like initialization and Uninitialization
10+
/// </summary>
11+
public interface IExternalKernelProcessMessageChannel
12+
{
13+
/// <summary>
14+
/// Initialization of the external messaging channel used
15+
/// </summary>
16+
/// <returns>A <see cref="ValueTask"/></returns>
17+
public abstract ValueTask Initialize();
18+
19+
/// <summary>
20+
/// Uninitialization of the external messaging channel used
21+
/// </summary>
22+
/// <returns>A <see cref="ValueTask"/></returns>
23+
public abstract ValueTask Uninitialize();
24+
25+
/// <summary>
26+
/// Emits the specified event from the step outside the SK process
27+
/// </summary>
28+
/// <param name="externalTopicEvent">name of the topic to be used externally as the event name</param>
29+
/// <param name="eventData">data to be transmitted externally</param>
30+
/// <returns></returns>
31+
public abstract Task EmitExternalEventAsync(string externalTopicEvent, object? eventData);
32+
}

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

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,4 +27,10 @@ public abstract class KernelProcessContext
2727
/// </summary>
2828
/// <returns>A <see cref="Task{T}"/> where T is <see cref="KernelProcess"/></returns>
2929
public abstract Task<KernelProcess> GetStateAsync();
30+
31+
/// <summary>
32+
/// Gets the instance of <see cref="IExternalKernelProcessMessageChannel"/> used for external messages
33+
/// </summary>
34+
/// <returns></returns>
35+
public abstract Task<IExternalKernelProcessMessageChannel?> GetExternalMessageChannelAsync();
3036
}

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

Lines changed: 24 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,18 +10,21 @@ namespace Microsoft.SemanticKernel;
1010
public sealed class KernelProcessStepContext
1111
{
1212
private readonly IKernelProcessMessageChannel _stepMessageChannel;
13+
private readonly IExternalKernelProcessMessageChannel? _externalMessageChannel;
1314

1415
/// <summary>
1516
/// Initializes a new instance of the <see cref="KernelProcessStepContext"/> class.
1617
/// </summary>
1718
/// <param name="channel">An instance of <see cref="IKernelProcessMessageChannel"/>.</param>
18-
public KernelProcessStepContext(IKernelProcessMessageChannel channel)
19+
/// <param name="externalMessageChannel">An instance of <see cref="IExternalKernelProcessMessageChannel"/></param>
20+
public KernelProcessStepContext(IKernelProcessMessageChannel channel, IExternalKernelProcessMessageChannel? externalMessageChannel = null)
1921
{
2022
this._stepMessageChannel = channel;
23+
this._externalMessageChannel = externalMessageChannel;
2124
}
2225

2326
/// <summary>
24-
/// Emit an event from the current step.
27+
/// Emit an SK process event from the current step.
2528
/// </summary>
2629
/// <param name="processEvent">An instance of <see cref="KernelProcessEvent"/> to be emitted from the <see cref="KernelProcessStep"/></param>
2730
/// <returns>A <see cref="ValueTask"/></returns>
@@ -31,7 +34,7 @@ public ValueTask EmitEventAsync(KernelProcessEvent processEvent)
3134
}
3235

3336
/// <summary>
34-
/// Emit an event from the current step with a simplified method signature.
37+
/// Emit an SK process event from the current step with a simplified method signature.
3538
/// </summary>
3639
/// <param name="eventId"></param>
3740
/// <param name="data"></param>
@@ -52,4 +55,22 @@ public ValueTask EmitEventAsync(
5255
Visibility = visibility
5356
});
5457
}
58+
59+
/// <summary>
60+
/// Emit an external event to through a <see cref="IExternalKernelProcessMessageChannel"/>
61+
/// component if connected from within the SK process
62+
/// </summary>
63+
/// <param name="topicName"></param>
64+
/// <param name="processEventData"></param>
65+
/// <returns></returns>
66+
/// <exception cref="KernelException"></exception>
67+
public async Task EmitExternalEventAsync(string topicName, object? processEventData = null)
68+
{
69+
if (this._externalMessageChannel == null)
70+
{
71+
throw new KernelException($"External message channel not configured for step with topic {topicName}");
72+
}
73+
74+
await this._externalMessageChannel.EmitExternalEventAsync(topicName, processEventData).ConfigureAwait(false);
75+
}
5576
}

‎dotnet/src/Experimental/Process.IntegrationTestHost.Dapr/Controllers/ProcessTestController.cs‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
using Microsoft.AspNetCore.Mvc;
66
using Microsoft.SemanticKernel;
77
using Microsoft.SemanticKernel.Process.Serialization;
8+
using SemanticKernel.Process.IntegrationTests.CloudEvents;
89

910
namespace SemanticKernel.Process.IntegrationTests.Controllers;
1011

@@ -72,6 +73,23 @@ public async Task<IActionResult> GetProcessAsync(string processId)
7273
return this.Ok(daprProcess);
7374
}
7475

76+
/// <summary>
77+
/// Retrieves current state of the MockCloudEventClient used in the running process
78+
/// </summary>
79+
/// <param name="processId">The Id of the process.</param>
80+
/// <param name="cloudClient">Mock Cloud client ingested via dependency injection</param>
81+
/// <returns></returns>
82+
[HttpGet("processes/{processId}/mockCloudClient")]
83+
public Task<IActionResult> GetMockCloudClient(string processId, MockCloudEventClient cloudClient)
84+
{
85+
if (!s_processes.TryGetValue(processId, out DaprKernelProcessContext? context))
86+
{
87+
return Task.FromResult<IActionResult>(this.NotFound());
88+
}
89+
90+
return Task.FromResult<IActionResult>(this.Ok(cloudClient));
91+
}
92+
7593
/// <summary>
7694
/// Checks the health of the Dapr runtime by attempting to send a message to a health actor.
7795
/// </summary>

‎dotnet/src/Experimental/Process.IntegrationTestHost.Dapr/Program.cs‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22

33
using Microsoft.SemanticKernel;
44
using SemanticKernel.Process.IntegrationTests;
5+
using SemanticKernel.Process.IntegrationTests.CloudEvents;
56

67
var builder = WebApplication.CreateBuilder(args);
78

@@ -15,6 +16,10 @@
1516
// Configure the Kernel with DI. This is required for dependency injection to work with processes.
1617
builder.Services.AddKernel();
1718

19+
// Configure IExternalKernelProcessMessageChannel used for testing purposes
20+
builder.Services.AddSingleton<IExternalKernelProcessMessageChannel>(MockCloudEventClient.Instance);
21+
builder.Services.AddSingleton(MockCloudEventClient.Instance);
22+
1823
// Configure Dapr
1924
builder.Services.AddActors(static options =>
2025
{

‎dotnet/src/Experimental/Process.IntegrationTestRunner.Dapr/DaprTestProcessContext.cs‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
using Microsoft.SemanticKernel;
66
using Microsoft.SemanticKernel.Process;
77
using Microsoft.SemanticKernel.Process.Serialization;
8+
using SemanticKernel.Process.IntegrationTests.CloudEvents;
89

910
namespace SemanticKernel.Process.IntegrationTests;
1011
internal sealed class DaprTestProcessContext : KernelProcessContext
@@ -68,4 +69,14 @@ public override Task StopAsync()
6869
{
6970
throw new NotImplementedException();
7071
}
72+
73+
public override async Task<IExternalKernelProcessMessageChannel?> GetExternalMessageChannelAsync()
74+
{
75+
var response = await this._httpClient.GetFromJsonAsync<MockCloudEventClient>($"http://localhost:5200/processes/{this._processId}/mockCloudClient", options: this._serializerOptions);
76+
return response switch
77+
{
78+
null => throw new InvalidOperationException("Process not found"),
79+
_ => response
80+
};
81+
}
7182
}

‎dotnet/src/Experimental/Process.IntegrationTestRunner.Dapr/ProcessTestFixture.cs‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -121,9 +121,11 @@ private async Task WaitForHostStartupAsync()
121121
/// <param name="process">The process to start.</param>
122122
/// <param name="kernel">An instance of <see cref="Kernel"/></param>
123123
/// <param name="initialEvent">An optional initial event.</param>
124+
/// <param name="externalMessageChannel">channel used for external messages</param>
124125
/// <returns>A <see cref="Task{KernelProcessContext}"/></returns>
125-
public async Task<KernelProcessContext> StartProcessAsync(KernelProcess process, Kernel kernel, KernelProcessEvent initialEvent)
126+
public async Task<KernelProcessContext> StartProcessAsync(KernelProcess process, Kernel kernel, KernelProcessEvent initialEvent, IExternalKernelProcessMessageChannel? externalMessageChannel = null)
126127
{
128+
// Actual Kernel injection of Kernel and ExternalKernelProcessMessageChannel is in dotnet\src\Experimental\Process.IntegrationTestHost.Dapr\Program.cs
127129
var context = new DaprTestProcessContext(process, this._httpClient!);
128130
await context.StartWithEventAsync(initialEvent);
129131
return context;

‎dotnet/src/Experimental/Process.IntegrationTestRunner.Local/ProcessTestFixture.cs‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,9 +17,10 @@ public class ProcessTestFixture
1717
/// <param name="process">The process to start.</param>
1818
/// <param name="kernel">An instance of <see cref="Kernel"/></param>
1919
/// <param name="initialEvent">An optional initial event.</param>
20+
/// <param name="externalMessageChannel">channel used for external messages</param>
2021
/// <returns>A <see cref="Task{KernelProcessContext}"/></returns>
21-
public async Task<KernelProcessContext> StartProcessAsync(KernelProcess process, Kernel kernel, KernelProcessEvent initialEvent)
22+
public async Task<KernelProcessContext> StartProcessAsync(KernelProcess process, Kernel kernel, KernelProcessEvent initialEvent, IExternalKernelProcessMessageChannel? externalMessageChannel = null)
2223
{
23-
return await process.StartAsync(kernel, initialEvent);
24+
return await process.StartAsync(kernel, initialEvent, externalMessageChannel);
2425
}
2526
}
Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
// Copyright (c) Microsoft. All rights reserved.
2+
3+
using System.Collections.Generic;
4+
using System.Threading.Tasks;
5+
using Microsoft.SemanticKernel;
6+
7+
namespace SemanticKernel.Process.IntegrationTests.CloudEvents;
8+
/// <summary>
9+
/// Class used for testing purposes to mock emitting external cloud events
10+
/// </summary>
11+
public class MockCloudEventClient : IExternalKernelProcessMessageChannel
12+
{
13+
/// <summary>
14+
/// Initialization counter for testing
15+
/// </summary>
16+
public int InitializationCounter { get; set; } = 0;
17+
/// <summary>
18+
/// Uninitialization counter for testing
19+
/// </summary>
20+
public int UninitializationCounter { get; set; } = 0;
21+
/// <summary>
22+
/// Captures cloud events emitted for testing
23+
/// </summary>
24+
public List<MockCloudEventData> CloudEvents { get; set; } = [];
25+
26+
private static MockCloudEventClient? s_instance = null;
27+
28+
/// <summary>
29+
/// Instance of <see cref="MockCloudEventClient"/> when used as singleton
30+
/// </summary>
31+
public static MockCloudEventClient Instance
32+
{
33+
get
34+
{
35+
return s_instance ??= new MockCloudEventClient();
36+
}
37+
}
38+
39+
/// <inheritdoc/>
40+
public Task EmitExternalEventAsync(string externalTopicEvent, object? eventData)
41+
{
42+
if (eventData != null)
43+
{
44+
this.CloudEvents.Add(new() { TopicName = externalTopicEvent, Data = (string)eventData });
45+
}
46+
47+
return Task.CompletedTask;
48+
}
49+
50+
/// <inheritdoc/>
51+
public ValueTask Initialize()
52+
{
53+
this.InitializationCounter++;
54+
return ValueTask.CompletedTask;
55+
}
56+
57+
/// <inheritdoc/>
58+
public ValueTask Uninitialize()
59+
{
60+
this.UninitializationCounter++;
61+
return ValueTask.CompletedTask;
62+
}
63+
}
Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
// Copyright (c) Microsoft. All rights reserved.
2+
3+
namespace SemanticKernel.Process.IntegrationTests.CloudEvents;
4+
5+
/// <summary>
6+
/// Mock cloud event data used for testing purposes only
7+
/// </summary>
8+
public class MockCloudEventData
9+
{
10+
/// <summary>
11+
/// Name of the mock topic
12+
/// </summary>
13+
public required string TopicName { get; set; }
14+
15+
/// <summary>
16+
/// Data emitted in the mock cloud event
17+
/// </summary>
18+
public string? Data { get; set; }
19+
}

0 commit comments

Comments
 (0)