.Net Processes: Updated to process abstractions and core builders in preparation for Dapr runtime (#9285)

### Description

This PR is the first in a series that will enable the Dapr runtime for
Processes. This change makes adjustments to the abstractions and core
builder that are mainly focused on supporting the DataContract
serialization used for Dapr actor remoted function calling.

### 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 😄

---------

Co-authored-by: Ben Thomas <bentho@microsoft.com>
Co-authored-by: Chris <66376200+crickman@users.noreply.github.com>

Author: 3 people

.vscode/settings.json

@@ -1,8 +1,6 @@
 {
   "prettier.enable": true,
-  "css.lint.validProperties": [
-    "composes"
-  ],
+  "css.lint.validProperties": ["composes"],
   "editor.formatOnType": true,
   "editor.formatOnSave": true,
   "editor.formatOnPaste": true,
@@ -15,13 +13,9 @@
   "editor.bracketPairColorization.enabled": true,
   "editor.guides.bracketPairs": "active",
   "python.formatting.provider": "autopep8",
-  "python.formatting.autopep8Args": [
-    "--max-line-length=120"
-  ],
+  "python.formatting.autopep8Args": ["--max-line-length=120"],
   "notebook.output.textLineLimit": 500,
-  "python.analysis.extraPaths": [
-    "./python/src"
-  ],
+  "python.analysis.extraPaths": ["./python/src"],
   "javascript.updateImportsOnFileMove.enabled": "always",
   "search.exclude": {
     "**/node_modules": true,
@@ -71,31 +65,34 @@
     "**/Thumbs.db": true
   },
   "cSpell.words": [
+    "Dapr",
     "Partitioner",
+    "Pregel",
     "Prompty",
-    "SKEXP"
+    "SKEXP",
+    "superstep",
+    "Supersteps",
+    "typeref"
   ],
   "[java]": {
     "editor.formatOnSave": false,
     "editor.tabSize": 4,
     "editor.codeActionsOnSave": {
       "source.fixAll": "never"
-    },
+    }
   },
   "emeraldwalk.runonsave": {
     "commands": [
       {
         "match": "\\.java$",
         "cmd": "java -Xmx128m -jar ${workspaceFolder}/java/utilities/google-java-format-1.17.0-all-deps.jar --replace --aosp ${file}"
-      },
-    ],
+      }
+    ]
   },
   "java.debug.settings.onBuildFailureProceed": true,
   "java.compile.nullAnalysis.mode": "disabled",
   "dotnet.defaultSolution": "dotnet\\SK-dotnet.sln",
-  "python.testing.pytestArgs": [
-    "python/tests"
-  ],
+  "python.testing.pytestArgs": ["python/tests"],
   "python.testing.unittestEnabled": false,
   "python.testing.pytestEnabled": true
-}
+}

dotnet/samples/GettingStartedWithProcesses/SharedSteps/ScriptedUserInputStep.cs

@@ -41,10 +41,9 @@ public virtual void PopulateUserInputs(UserInputState state)
     /// <returns>A <see cref="ValueTask"/></returns>
     public override ValueTask ActivateAsync(KernelProcessStepState<UserInputState> state)
     {
-        state.State ??= new();
         _state = state.State;
 
-        PopulateUserInputs(_state);
+        PopulateUserInputs(_state!);
 
         return ValueTask.CompletedTask;
     }

dotnet/src/Experimental/Process.Abstractions/KernelProcessEdge.cs

@@ -1,31 +1,37 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+using System.Runtime.Serialization;
+
 namespace Microsoft.SemanticKernel;
 
 /// <summary>
 /// A serializable representation of an edge between a source <see cref="KernelProcessStep"/> and a <see cref="KernelProcessFunctionTarget"/>.
 /// </summary>
+[DataContract]
+[KnownType(typeof(KernelProcessFunctionTarget))]
 public sealed class KernelProcessEdge
 {
     /// <summary>
     /// The unique identifier of the source Step.
     /// </summary>
-    public string SourceStepId { get; }
+    [DataMember]
+    public string SourceStepId { get; init; }
 
     /// <summary>
     /// The collection of <see cref="KernelProcessFunctionTarget"/>s that are the output of the source Step.
     /// </summary>
-    public KernelProcessFunctionTarget OutputTarget { get; }
+    [DataMember]
+    public KernelProcessFunctionTarget OutputTarget { get; init; }
 
     /// <summary>
     /// Creates a new instance of the <see cref="KernelProcessEdge"/> class.
     /// </summary>
-    public KernelProcessEdge(string sourceStepId, KernelProcessFunctionTarget outputTargets)
+    public KernelProcessEdge(string sourceStepId, KernelProcessFunctionTarget outputTarget)
     {
         Verify.NotNullOrWhiteSpace(sourceStepId);
-        Verify.NotNull(outputTargets);
+        Verify.NotNull(outputTarget);
 
         this.SourceStepId = sourceStepId;
-        this.OutputTarget = outputTargets;
+        this.OutputTarget = outputTarget;
     }
 }

dotnet/src/Experimental/Process.Abstractions/KernelProcessFunctionTarget.cs

@@ -1,10 +1,13 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+using System.Runtime.Serialization;
+
 namespace Microsoft.SemanticKernel;
 
 /// <summary>
 /// A serializable representation of a specific parameter of a specific function of a specific Step.
 /// </summary>
+[DataContract]
 public record KernelProcessFunctionTarget
 {
     /// <summary>
@@ -24,20 +27,24 @@ public KernelProcessFunctionTarget(string stepId, string functionName, string? p
     /// <summary>
     /// The unique identifier of the Step being targeted.
     /// </summary>
+    [DataMember]
     public string StepId { get; init; }
 
     /// <summary>
     /// The name if the Kernel Function to target.
     /// </summary>
+    [DataMember]
     public string FunctionName { get; init; }
 
     /// <summary>
     /// The name of the parameter to target. This may be null if the function has no parameters.
     /// </summary>
+    [DataMember]
     public string? ParameterName { get; init; }
 
     /// <summary>
     /// The unique identifier for the event to target. This may be null if the target is not a sub-process.
     /// </summary>
+    [DataMember]
     public string? TargetEventId { get; init; }
 }

dotnet/src/Experimental/Process.Abstractions/KernelProcessState.cs

@@ -1,14 +1,17 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+using System.Runtime.Serialization;
+
 namespace Microsoft.SemanticKernel;
 
 /// <summary>
 /// Represents the state of a process.
 /// </summary>
+[DataContract]
 public sealed record KernelProcessState : KernelProcessStepState
 {
     /// <summary>
-    /// Initializes a new instance of the <see cref="KernelProcessStepState"/> class.
+    /// Initializes a new instance of the <see cref="KernelProcessState"/> class.
     /// </summary>
     /// <param name="name">The name of the associated <see cref="KernelProcessStep"/></param>
     /// <param name="id">The Id of the associated <see cref="KernelProcessStep"/></param>

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

@@ -54,5 +54,8 @@ public KernelProcessStepInfo(Type innerStepType, KernelProcessStepState state, D
         this.InnerStepType = innerStepType;
         this._outputEdges = edges;
         this._state = state;
+
+        // Register the state as a know type for the DataContractSerialization used by Dapr.
+        KernelProcessState.RegisterDerivedType(state.GetType());
     }
 }

dotnet/src/Experimental/Process.Abstractions/KernelProcessStepState.cs

@@ -1,22 +1,51 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+using System;
+using System.Collections.Generic;
+using System.Runtime.Serialization;
+
 namespace Microsoft.SemanticKernel;
 
 /// <summary>
 /// Represents the state of an individual step in a process.
 /// </summary>
+[DataContract]
+[KnownType(nameof(GetKnownTypes))]
 public record KernelProcessStepState
 {
+    /// <summary>
+    /// A set of known types that may be used in serialization.
+    /// </summary>
+    private readonly static HashSet<Type> s_knownTypes = [];
+
+    /// <summary>
+    /// Used to dynamically provide the set of known types for serialization.
+    /// </summary>
+    /// <returns></returns>
+    private static HashSet<Type> GetKnownTypes() => s_knownTypes;
+
+    /// <summary>
+    /// Registers a derived type for serialization. Types registered here are used by the KnownType attribute
+    /// to support DataContractSerialization of derived types as required to support Dapr.
+    /// </summary>
+    /// <param name="derivedType">A Type that derives from <typeref name="KernelProcessStepState"/></param>
+    internal static void RegisterDerivedType(Type derivedType)
+    {
+        s_knownTypes.Add(derivedType);
+    }
+
     /// <summary>
     /// The identifier of the Step which is required to be unique within an instance of a Process.
     /// This may be null until a process containing this step has been invoked.
     /// </summary>
+    [DataMember]
     public string? Id { get; init; }
 
     /// <summary>
-    /// The name of the Step. This is itended to be human readable and is not required to be unique. If
+    /// The name of the Step. This is intended to be human readable and is not required to be unique. If
     /// not provided, the name will be derived from the steps .NET type.
     /// </summary>
+    [DataMember]
     public string Name { get; init; }
 
     /// <summary>
@@ -37,12 +66,14 @@ public KernelProcessStepState(string name, string? id = null)
 /// Represents the state of an individual step in a process that includes a user-defined state object.
 /// </summary>
 /// <typeparam name="TState">The type of the user-defined state.</typeparam>
+[DataContract]
 public sealed record KernelProcessStepState<TState> : KernelProcessStepState where TState : class, new()
 {
     /// <summary>
     /// The user-defined state object associated with the Step.
     /// </summary>
-    public TState? State { get; set; }
+    [DataMember]
+    public TState? State { get; init; }
 
     /// <summary>
     /// Initializes a new instance of the <see cref="KernelProcessStepState"/> class.

dotnet/src/Experimental/Process.Core/Internal/EndStep.cs

@@ -9,7 +9,7 @@ namespace Microsoft.SemanticKernel;
 /// </summary>
 internal sealed class EndStep : ProcessStepBuilder
 {
-    private const string EndStepValue = "END";
+    private const string EndStepValue = "Microsoft.SemanticKernel.Process.EndStep";
 
     /// <summary>
     /// The name of the end step.

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

@@ -115,6 +115,22 @@ public ProcessStepBuilder AddStepFromType<TStep>(string? name = null) where TSte
         return stepBuilder;
     }
 
+    /// <summary>
+    /// Adds a step to the process and define it's initial user-defined state.
+    /// </summary>
+    /// <typeparam name="TStep">The step Type.</typeparam>
+    /// <typeparam name="TState">The state Type.</typeparam>
+    /// <param name="initialState">The initial state of the step.</param>
+    /// <param name="name">The name of the step. This parameter is optional.</param>
+    /// <returns>An instance of <see cref="ProcessStepBuilder"/></returns>
+    public ProcessStepBuilder AddStepFromType<TStep, TState>(TState initialState, string? name = null) where TStep : KernelProcessStep<TState> where TState : class, new()
+    {
+        var stepBuilder = new ProcessStepBuilder<TStep>(name, initialState);
+        this._steps.Add(stepBuilder);
+
+        return stepBuilder;
+    }
+
     /// <summary>
     /// Adds a sub process to the process.
     /// </summary>

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

@@ -194,13 +194,21 @@ protected ProcessStepBuilder(string name)
 /// </summary>
 public sealed class ProcessStepBuilder<TStep> : ProcessStepBuilder where TStep : KernelProcessStep
 {
+    /// <summary>
+    /// The initial state of the step. This may be null if the step does not have any state.
+    /// </summary>
+    private readonly object? _initialState;
+
     /// <summary>
     /// Creates a new instance of the <see cref="ProcessStepBuilder"/> class. If a name is not provided, the name will be derived from the type of the step.
     /// </summary>
-    public ProcessStepBuilder(string? name = null)
+    /// <param name="name">Optional: The name of the step.</param>
+    /// <param name="initialState">Optional: The initial state of the step.</param>
+    internal ProcessStepBuilder(string? name = null, object? initialState = default)
         : base(name ?? typeof(TStep).Name)
     {
         this.FunctionsDict = this.GetFunctionMetadataMap();
+        this._initialState = initialState;
     }
 
     /// <summary>
@@ -221,7 +229,14 @@ internal override KernelProcessStepInfo BuildStep()
             var stateType = typeof(KernelProcessStepState<>).MakeGenericType(userStateType);
             Verify.NotNull(stateType);
 
+            // If the step has a user-defined state then we need to validate that the initial state is of the correct type.
+            if (this._initialState is not null && this._initialState.GetType() != userStateType)
+            {
+                throw new KernelException($"The initial state provided for step {this.Name} is not of the correct type. The expected type is {userStateType.Name}.");
+            }
+
             stateObject = (KernelProcessStepState?)Activator.CreateInstance(stateType, this.Name, this.Id);
+            stateType.GetProperty(nameof(KernelProcessStepState<object>.State))?.SetValue(stateObject, this._initialState);
         }
         else
         {