refactor: Rename and simplify interface around getting typed data out of ExternalRequest/Response

* Also adds hints around using value types in PortableValue

Author: lokitoth

dotnet/samples/GettingStarted/Workflows/Agents/GroupChatToolApproval/Program.cs

@@ -101,7 +101,7 @@ private static async Task Main()
             {
                 case RequestInfoEvent e:
                 {
-                    if (e.Request.DataIs(out FunctionApprovalRequestContent? approvalRequestContent))
+                    if (e.Request.TryGetDataAs(out FunctionApprovalRequestContent? approvalRequestContent))
                     {
                         Console.WriteLine();
                         Console.WriteLine($"[APPROVAL REQUIRED] From agent: {e.Request.PortInfo.PortId}");

dotnet/samples/GettingStarted/Workflows/Checkpoint/CheckpointWithHumanInTheLoop/Program.cs

@@ -98,8 +98,7 @@ private static async Task Main()
 
     private static ExternalResponse HandleExternalRequest(ExternalRequest request)
     {
-        var signal = request.DataAs<SignalWithNumber>();
-        if (signal is not null)
+        if (request.TryGetDataAs<SignalWithNumber>(out var signal))
         {
             switch (signal.Signal)
             {

dotnet/samples/GettingStarted/Workflows/HumanInTheLoop/HumanInTheLoopBasic/Program.cs

@@ -50,7 +50,8 @@ private static ExternalResponse HandleExternalRequest(ExternalRequest request)
     {
         if (request.DataIs<NumberSignal>())
         {
-            switch (request.DataAs<NumberSignal>())
+            // We explicitly use .Data.As because we rely on the value defaulting to NumberSignal.Init when not set
+            switch (request.Data.As<NumberSignal>())
             {
                 case NumberSignal.Init:
                     int initialGuess = ReadIntegerFromConsole("Please provide your initial guess: ");

dotnet/src/Microsoft.Agents.AI.Workflows/ExternalRequest.cs

@@ -15,13 +15,6 @@ namespace Microsoft.Agents.AI.Workflows;
 /// <param name="Data">The data contained in the request.</param>
 public record ExternalRequest(RequestPortInfo PortInfo, string RequestId, PortableValue Data)
 {
-    /// <summary>
-    /// Attempts to retrieve the underlying data as the specified type.
-    /// </summary>
-    /// <typeparam name="TValue">The type to which the data should be cast or converted.</typeparam>
-    /// <returns>The data cast to the specified type, or null if the data cannot be cast to the specified type.</returns>
-    public TValue? DataAs<TValue>() => this.Data.As<TValue>();
-
     /// <summary>
     /// Determines whether the underlying data is of the specified type.
     /// </summary>
@@ -34,7 +27,16 @@ public record ExternalRequest(RequestPortInfo PortInfo, string RequestId, Portab
     /// </summary>
     /// <typeparam name="TValue">The type to compare with the underlying data.</typeparam>
     /// <returns>true if the underlying data is of type TValue; otherwise, false.</returns>
-    public bool DataIs<TValue>([NotNullWhen(true)] out TValue? value) => this.Data.Is(out value);
+    public bool TryGetDataAs<TValue>([NotNullWhen(true)] out TValue? value) => this.Data.Is(out value);
+
+    /// <summary>
+    /// Attempts to retrieve the underlying data as the specified type.
+    /// </summary>
+    /// <param name="targetType">The type to which the data should be cast or converted.</param>
+    /// <param name="value">When this method returns <see langword="true"/>, contains the value of type
+    /// <paramref name="targetType"/> if the data is available and compatible.</param>
+    /// <returns>true if the data is present and can be cast to <paramref name="targetType"/>; otherwise, false.</returns>
+    public bool TryGetDataAs(Type targetType, [NotNullWhen(true)] out object? value) => this.Data.IsType(targetType, out value);
 
     /// <summary>
     /// Creates a new <see cref="ExternalRequest"/> for the specified input port and data payload.

dotnet/src/Microsoft.Agents.AI.Workflows/ExternalResponse.cs

@@ -14,13 +14,6 @@ namespace Microsoft.Agents.AI.Workflows;
 /// <param name="Data">The data contained in the response.</param>
 public record ExternalResponse(RequestPortInfo PortInfo, string RequestId, PortableValue Data)
 {
-    /// <summary>
-    /// Attempts to retrieve the underlying data as the specified type.
-    /// </summary>
-    /// <typeparam name="TValue">The type to which the data should be cast or converted.</typeparam>
-    /// <returns>The data cast to the specified type, or null if the data cannot be cast to the specified type.</returns>
-    public TValue? DataAs<TValue>() => this.Data.As<TValue>();
-
     /// <summary>
     /// Determines whether the underlying data is of the specified type.
     /// </summary>
@@ -35,14 +28,7 @@ public record ExternalResponse(RequestPortInfo PortInfo, string RequestId, Porta
     /// <param name="value">When this method returns, contains the value of type <typeparamref name="TValue"/> if the data is
     /// available and compatible.</param>
     /// <returns>true if the data is present and can be cast to <typeparamref name="TValue"/>; otherwise, false.</returns>
-    public bool DataIs<TValue>([NotNullWhen(true)] out TValue? value) => this.Data.Is(out value);
-
-    /// <summary>
-    /// Attempts to retrieve the underlying data as the specified type.
-    /// </summary>
-    /// <param name="targetType">The type to which the data should be cast or converted.</param>
-    /// <returns>The data cast to the specified type, or null if the data cannot be cast to the specified type.</returns>
-    public object? DataAs(Type targetType) => this.Data.AsType(targetType);
+    public bool TryGetDataAs<TValue>([NotNullWhen(true)] out TValue? value) => this.Data.Is(out value);
 
     /// <summary>
     /// Attempts to retrieve the underlying data as the specified type.
@@ -51,5 +37,5 @@ public record ExternalResponse(RequestPortInfo PortInfo, string RequestId, Porta
     /// <param name="value">When this method returns <see langword="true"/>, contains the value of type
     /// <paramref name="targetType"/> if the data is available and compatible.</param>
     /// <returns>true if the data is present and can be cast to <paramref name="targetType"/>; otherwise, false.</returns>
-    public bool DataIs(Type targetType, [NotNullWhen(true)] out object? value) => this.Data.IsType(targetType, out value);
+    public bool TryGetDataAs(Type targetType, [NotNullWhen(true)] out object? value) => this.Data.IsType(targetType, out value);
 }

dotnet/src/Microsoft.Agents.AI.Workflows/PortableValue.cs

@@ -96,7 +96,8 @@ public override int GetHashCode()
     /// </summary>
     /// <remarks>If the underlying value implements delayed deserialization, this method will attempt to
     /// deserialize it to the specified type. If the value is already of the requested type, it is returned directly.
-    /// Otherwise, the default value for TValue is returned.
+    /// Otherwise, the default value for TValue is returned. For value types, the default is not <see langword="null"/>,
+    /// UNLESS <typeparamref name="TValue"/> is nullable, e.g. <c>int?</c>.
     /// </remarks>
     /// <typeparam name="TValue">The type to which the value should be cast or deserialized.</typeparam>
     /// <returns>The value cast or deserialized to type TValue if possible; otherwise, the default value for type TValue.</returns>

dotnet/src/Microsoft.Agents.AI.Workflows/RouteBuilder.cs

@@ -158,7 +158,7 @@ internal RouteBuilder AddPortHandler<TRequest, TResponse>(string id, Func<TRespo
 
         async ValueTask<ExternalResponse?> InvokeHandlerAsync(ExternalResponse response, IWorkflowContext context, CancellationToken cancellationToken)
         {
-            if (!response.DataIs(out TResponse? typedResponse))
+            if (!response.TryGetDataAs(out TResponse? typedResponse))
             {
                 throw new InvalidOperationException($"Received response data is not of expected type {typeof(TResponse).FullName} for port {port.Id}.");
             }

dotnet/src/Shared/Workflows/Execution/WorkflowRunner.cs

@@ -272,9 +272,10 @@ public async Task ExecuteAsync(Func<Workflow> workflowProvider, string input)
     /// </summary>
     private async ValueTask<ExternalInputResponse> HandleExternalRequestAsync(ExternalRequest request)
     {
-        ExternalInputRequest inputRequest =
-            request.DataAs<ExternalInputRequest>() ??
+        if (!request.TryGetDataAs<ExternalInputRequest>(out var inputRequest))
+        {
             throw new InvalidOperationException($"Expected external request type: {request.GetType().Name}.");
+        }
 
         List<ChatMessage> responseMessages = [];
 

dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/Sample/09_Subworkflow_ExternalRequest.cs

@@ -237,14 +237,14 @@ public static async ValueTask<List<RequestFinished>> RunAsync(TextWriter writer,
 
         foreach (ExternalRequest request in resourceRequests)
         {
-            ResourceRequest resourceRequest = request.DataAs<ResourceRequest>()!;
+            ResourceRequest resourceRequest = request.Data.As<ResourceRequest>()!;
             resourceRequest.Id.Should().BeOneOf(ResourceMissIds);
             responses.Add(request.CreateResponse(Part2FinishedResponses[resourceRequest.Id].ResourceResponse!));
         }
 
         foreach (ExternalRequest request in policyRequests)
         {
-            PolicyCheckRequest policyRequest = request.DataAs<PolicyCheckRequest>()!;
+            PolicyCheckRequest policyRequest = request.Data.As<PolicyCheckRequest>()!;
             policyRequest.Id.Should().BeOneOf(PolicyMissIds);
             responses.Add(request.CreateResponse(Part2FinishedResponses[policyRequest.Id].PolicyResponse!));
         }
@@ -372,7 +372,7 @@ void ConfigureRoutes(RouteBuilder routeBuilder)
 
     private async ValueTask UnwrapAndHandleRequestAsync(ExternalRequest request, IWorkflowContext context, CancellationToken cancellationToken = default)
     {
-        if (request.DataIs(out ResourceRequest? resourceRequest))
+        if (request.TryGetDataAs(out ResourceRequest? resourceRequest))
         {
             ResourceResponse? response = await this.TryHandleResourceRequestAsync(resourceRequest, context, cancellationToken)
                                                    .ConfigureAwait(false);
@@ -459,7 +459,7 @@ void ConfigureRoutes(RouteBuilder routeBuilder)
 
     private async ValueTask UnwrapAndHandleRequestAsync(ExternalRequest request, IWorkflowContext context)
     {
-        if (request.DataIs(out PolicyCheckRequest? policyRquest))
+        if (request.TryGetDataAs(out PolicyCheckRequest? policyRquest))
         {
             PolicyResponse? response = await this.TryHandlePolicyCheckRequestAsync(policyRquest, context)
                                                  .ConfigureAwait(false);

dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/TestRequestAgent.cs

@@ -325,7 +325,7 @@ internal IEnumerable<ExternalResponse> ValidateUnpairedRequests(List<ExternalReq
 
         static TRequest AssertAndExtractRequestContent<TRequest>(ExternalRequest request)
         {
-            request.DataIs(out TRequest? content).Should().BeTrue();
+            request.TryGetDataAs(out TRequest? content).Should().BeTrue();
             return content!;
         }
     }