[BREAKING] Obsoleting ReflectingExecutor in favor of source gen (#3380)

* Initial working version with tests.

* Updates to validate class data once instead of for each handler method. Also updated Diagnostics Ids to format of MAFGENWF{NUM}

* Formatting and trying to fix generation project pack.

* Another atempt at getting the genrators project to build.

* More attempts to fix generator build and pack.

* Fixing file encodings.

* Initail round of cleanup.

* Trying to fix packing.

* Still trying to fix pipeline pack.

* Remove obsolescence markers, sample updates, and docs from generator branch.

This commit separates the generator core functionality from the
deprecation of ReflectingExecutor. The removed changes will be
re-added in a dependent branch (wf-obsolete-reflector).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Mark ReflectingExecutor and IMessageHandler as obsolete.

This commit deprecates the reflection-based handler discovery approach
in favor of the new [MessageHandler] attribute with source generation.

Changes:
- Add [Obsolete] to ReflectingExecutor<T>, IMessageHandler<T>, IMessageHandler<T,R>
- Add #pragma to suppress warnings in internal reflection code
- Update Concurrent sample to use new [MessageHandler] pattern
- Add Directory.Build.props for samples to include generator
- Add documentation files explaining the migration

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Obsoleteing Reflector-based workflow code generation in favor of Source Generators and updating some samples to use new pattern.

This commit deprecates the reflection-based handler discovery approach
in favor of the new [MessageHandler] attribute with source generation.

Changes:
- Add [Obsolete] to ReflectingExecutor<T>, IMessageHandler<T>, IMessageHandler<T,R>
- Add #pragma to suppress warnings in internal reflection code
- Update Concurrent sample to use new [MessageHandler] pattern
- Add Directory.Build.props for samples to include generator
- Add documentation files explaining the migration

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Cleaning up temporary design and progress files.

---------

Co-authored-by: alliscode <bentho@microsoft.com>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Co-authored-by: Chris <66376200+crickman@users.noreply.github.com>

dotnet/src/Microsoft.Agents.AI.Workflows.Generators/Models/EquatableArray.cs

@@ -0,0 +1,121 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections;
+using System.Collections.Generic;
+using System.Collections.Immutable;
+
+namespace Microsoft.Agents.AI.Workflows.Generators.Models;
+
+/// <summary>
+/// A wrapper around <see cref="ImmutableArray{T}"/> that provides value-based equality.
+/// This is necessary for incremental generator caching since ImmutableArray uses reference equality.
+/// </summary>
+/// <remarks>
+/// Creates a new <see cref="EquatableArray{T}"/> from an <see cref="ImmutableArray{T}"/>.
+/// </remarks>
+internal readonly struct EquatableArray<T>(ImmutableArray<T> array) : IEquatable<EquatableArray<T>>, IEnumerable<T>
+    where T : IEquatable<T>
+{
+    private readonly ImmutableArray<T> _array = array.IsDefault ? ImmutableArray<T>.Empty : array;
+
+    /// <summary>
+    /// Gets the underlying array.
+    /// </summary>
+    public ImmutableArray<T> AsImmutableArray() => this._array;
+
+    /// <summary>
+    /// Gets the number of elements in the array.
+    /// </summary>
+    public int Length => this._array.Length;
+
+    /// <summary>
+    /// Gets the element at the specified index.
+    /// </summary>
+    public T this[int index] => this._array[index];
+
+    /// <summary>
+    /// Gets whether the array is empty.
+    /// </summary>
+    public bool IsEmpty => this._array.IsEmpty;
+
+    /// <inheritdoc/>
+    public bool Equals(EquatableArray<T> other)
+    {
+        if (this._array.Length != other._array.Length)
+        {
+            return false;
+        }
+
+        for (int i = 0; i < this._array.Length; i++)
+        {
+            if (!this._array[i].Equals(other._array[i]))
+            {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    /// <inheritdoc/>
+    public override bool Equals(object? obj)
+    {
+        return obj is EquatableArray<T> other && this.Equals(other);
+    }
+
+    /// <inheritdoc/>
+    public override int GetHashCode()
+    {
+        if (this._array.IsEmpty)
+        {
+            return 0;
+        }
+
+        var hashCode = 17;
+        foreach (var item in this._array)
+        {
+            hashCode = hashCode * 31 + (item?.GetHashCode() ?? 0);
+        }
+
+        return hashCode;
+    }
+
+    /// <inheritdoc/>
+    public IEnumerator<T> GetEnumerator()
+    {
+        return ((IEnumerable<T>)this._array).GetEnumerator();
+    }
+
+    /// <inheritdoc/>
+    IEnumerator IEnumerable.GetEnumerator()
+    {
+        return this.GetEnumerator();
+    }
+
+    /// <summary>
+    /// Equality operator.
+    /// </summary>
+    public static bool operator ==(EquatableArray<T> left, EquatableArray<T> right)
+    {
+        return left.Equals(right);
+    }
+
+    /// <summary>
+    /// Inequality operator.
+    /// </summary>
+    public static bool operator !=(EquatableArray<T> left, EquatableArray<T> right)
+    {
+        return !left.Equals(right);
+    }
+
+    /// <summary>
+    /// Creates an empty <see cref="EquatableArray{T}"/>.
+    /// </summary>
+    public static EquatableArray<T> Empty => new(ImmutableArray<T>.Empty);
+
+    /// <summary>
+    /// Implicit conversion from <see cref="ImmutableArray{T}"/>.
+    /// </summary>
+    public static implicit operator EquatableArray<T>(ImmutableArray<T> array) => new(array);
+}

dotnet/src/Microsoft.Agents.AI.Workflows/Attributes/YieldsMessageAttribute.cs

@@ -0,0 +1,49 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Agents.AI.Workflows;
+
+/// <summary>
+/// Declares that an executor may yield messages of the specified type as workflow outputs.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Apply this attribute to an <see cref="Executor"/> class to declare the types of messages
+/// it may yield via <see cref="IWorkflowContext.YieldOutputAsync"/>. This information is used
+/// for protocol validation and documentation.
+/// </para>
+/// <para>
+/// This attribute can be applied multiple times to declare multiple output types.
+/// It is inherited by derived classes, allowing base executors to declare common output types.
+/// </para>
+/// </remarks>
+/// <example>
+/// <code>
+/// [YieldsMessage(typeof(FinalResult))]
+/// [YieldsMessage(typeof(StreamChunk))]
+/// public partial class MyExecutor : Executor
+/// {
+///     // ...
+/// }
+/// </code>
+/// </example>
+[AttributeUsage(AttributeTargets.Class, AllowMultiple = true, Inherited = true)]
+public sealed class YieldsMessageAttribute : Attribute
+{
+    /// <summary>
+    /// Gets the type of message that the executor may yield.
+    /// </summary>
+    public Type Type { get; }
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="YieldsMessageAttribute"/> class.
+    /// </summary>
+    /// <param name="type">The type of message that the executor may yield.</param>
+    /// <exception cref="ArgumentNullException"><paramref name="type"/> is <see langword="null"/>.</exception>
+    public YieldsMessageAttribute(Type type)
+    {
+        this.Type = Throw.IfNull(type);
+    }
+}

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

@@ -1,5 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+#pragma warning disable CS0618 // Type or member is obsolete - Internal use of obsolete types for backward compatibility
+
 using System;
 using System.Collections.Generic;
 using System.Diagnostics;

dotnet/src/Microsoft.Agents.AI.Workflows/Reflection/IMessageHandler.cs

@@ -1,5 +1,6 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+using System;
 using System.Threading;
 using System.Threading.Tasks;
 
@@ -9,6 +10,12 @@ namespace Microsoft.Agents.AI.Workflows.Reflection;
 /// A message handler interface for handling messages of type <typeparamref name="TMessage"/>.
 /// </summary>
 /// <typeparam name="TMessage"></typeparam>
+/// <remarks>
+/// This interface is obsolete. Use the <see cref="MessageHandlerAttribute"/> on methods in a partial class
+/// deriving from <see cref="Executor"/> instead.
+/// </remarks>
+[Obsolete("Use [MessageHandler] attribute on methods in a partial class deriving from Executor. " +
+          "This interface will be removed in a future version.")]
 public interface IMessageHandler<TMessage>
 {
     /// <summary>
@@ -28,6 +35,12 @@ public interface IMessageHandler<TMessage>
 /// </summary>
 /// <typeparam name="TMessage">The type of message to handle.</typeparam>
 /// <typeparam name="TResult">The type of result returned after handling the message.</typeparam>
+/// <remarks>
+/// This interface is obsolete. Use the <see cref="MessageHandlerAttribute"/> on methods in a partial class
+/// deriving from <see cref="Executor"/> instead.
+/// </remarks>
+[Obsolete("Use [MessageHandler] attribute on methods in a partial class deriving from Executor. " +
+          "This interface will be removed in a future version.")]
 public interface IMessageHandler<TMessage, TResult>
 {
     /// <summary>

dotnet/src/Microsoft.Agents.AI.Workflows/Reflection/MessageHandlerInfo.cs

@@ -1,5 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+#pragma warning disable CS0618 // Type or member is obsolete - Internal use of obsolete types for backward compatibility
+
 using System;
 using System.Diagnostics;
 using System.Diagnostics.CodeAnalysis;

dotnet/src/Microsoft.Agents.AI.Workflows/Reflection/ReflectingExecutor.cs

@@ -1,5 +1,6 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+using System;
 using System.Diagnostics.CodeAnalysis;
 
 namespace Microsoft.Agents.AI.Workflows.Reflection;
@@ -10,6 +11,12 @@ namespace Microsoft.Agents.AI.Workflows.Reflection;
 /// <typeparam name="TExecutor">The actual type of the <see cref="ReflectingExecutor{TExecutor}"/>.
 /// This is used to reflectively discover handlers for messages without violating ILTrim requirements.
 /// </typeparam>
+/// <remarks>
+/// This type is obsolete. Use the <see cref="MessageHandlerAttribute"/> on methods in a partial class
+/// deriving from <see cref="Executor"/> instead.
+/// </remarks>
+[Obsolete("Use [MessageHandler] attribute on methods in a partial class deriving from Executor. " +
+          "This type will be removed in a future version.")]
 public class ReflectingExecutor<
     [DynamicallyAccessedMembers(
         ReflectionDemands.RuntimeInterfaceDiscoveryAndInvocation)

dotnet/src/Microsoft.Agents.AI.Workflows/Reflection/RouteBuilderExtensions.cs

@@ -1,5 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+#pragma warning disable CS0618 // Type or member is obsolete - Internal use of obsolete types for backward compatibility
+
 using System;
 using System.Collections.Generic;
 using System.Diagnostics;

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

@@ -1,5 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+#pragma warning disable CS0618 // Type or member is obsolete - Internal use of obsolete types for backward compatibility
+
 using System;
 using System.Threading;
 using System.Threading.Tasks;