Inventory MEAI001 experimental APIs into feature-specific diagnostic IDs (MEAI0001-MEAI0008)

docs/list-of-diagnostics.md

@@ -41,6 +41,14 @@ if desired.
 | `EXTEXP0016` | Hosting integration testing experiments |
 | `EXTEXP0017` | Contextual options experiments |
 | `EXTEXP0018` | HybridCache experiments |
+| `MEAI0001` | Image generation experiments |
+| `MEAI0002` | Speech-to-text experiments |
+| `MEAI0003` | Hosted MCP server experiments |
+| `MEAI0004` | Function approval experiments |
+| `MEAI0005` | Tool reduction experiments |
+| `MEAI0006` | Chat reduction experiments |
+| `MEAI0007` | Response continuations experiments |
+| `MEAI0008` | Code interpreter experiments |
 
 # Obsoletions
 

eng/MSBuild/LegacySupport.props

@@ -59,7 +59,7 @@
     <Compile Include="$(MSBuildThisFileDirectory)\..\..\src\LegacySupport\TaskWaitAsync\*.cs" LinkBase="LegacySupport\TaskWaitAsync" />
   </ItemGroup>
 
-  <ItemGroup Condition="'$(InjectExperimentalAttributeOnLegacy)' == 'true' AND ('$(TargetFramework)' == 'net462' or '$(TargetFramework)' == 'netstandard2.0' or '$(TargetFramework)' == 'netstandard2.1' or '$(TargetFramework)' == 'netcoreapp3.1' or '$(TargetFramework)' == 'net6.0' or '$(TargetFramework)' == 'net7.0')">
+  <ItemGroup Condition="'$(InjectExperimentalAttributeOnLegacy)' == 'true' AND ('$(TargetFramework)' == 'net462' or '$(TargetFramework)' == 'netstandard2.0' or '$(TargetFramework)' == 'netstandard2.1' or '$(TargetFramework)' == 'net8.0' or '$(TargetFramework)' == 'net9.0')">
     <Compile Include="$(MSBuildThisFileDirectory)\..\..\src\LegacySupport\ExperimentalAttribute\*.cs" LinkBase="LegacySupport\ExperimentalAttribute" />
   </ItemGroup>
 

src/LegacySupport/ExperimentalAttribute/ExperimentalAttribute.cs

@@ -1,7 +1,9 @@
 // Licensed to the .NET Foundation under one or more agreements.
 // The .NET Foundation licenses this file to you under the MIT license.
 
-#if !NET8_0_OR_GREATER
+#if !NET10_0_OR_GREATER
+
+#pragma warning disable CS0436 // Type conflicts with imported type
 
 namespace System.Diagnostics.CodeAnalysis;
 
@@ -42,6 +44,11 @@ public ExperimentalAttribute(string diagnosticId)
     /// </remarks>
     public string DiagnosticId { get; }
 
+    /// <summary>
+    /// Gets or sets an optional message associated with the experimental attribute.
+    /// </summary>
+    public string? Message { get; set; }
+
     /// <summary>
     ///  Gets or sets the URL for corresponding documentation.
     ///  The API accepts a format string instead of an actual URL, creating a generic URL that includes the diagnostic ID.
@@ -53,4 +60,6 @@ public ExperimentalAttribute(string diagnosticId)
 #pragma warning restore S3996 // URI properties should not be strings
 }
 
+#pragma warning restore CS0436
+
 #endif

src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatOptions.cs

@@ -5,6 +5,7 @@
 using System.Collections.Generic;
 using System.Diagnostics.CodeAnalysis;
 using System.Text.Json.Serialization;
+using Microsoft.Shared.DiagnosticIds;
 
 namespace Microsoft.Extensions.AI;
 
@@ -180,7 +181,7 @@ protected ChatOptions(ChatOptions? other)
     /// If the implementation does not support background responses, this property will be ignored.
     /// </para>
     /// </remarks>
-    [Experimental("MEAI001")]
+    [Experimental(DiagnosticIds.Experiments.ResponseContinuations, Message = DiagnosticIds.Experiments.ResponseContinuationsMessage, UrlFormat = DiagnosticIds.UrlFormat)]
     [JsonIgnore]
     public bool? AllowBackgroundResponses { get; set; }
 
@@ -195,7 +196,7 @@ protected ChatOptions(ChatOptions? other)
     /// can be polled for completion by obtaining the token from the <see cref="ChatResponse.ContinuationToken"/> property
     /// and passing it to this property on subsequent calls to <see cref="IChatClient.GetResponseAsync"/>.
     /// </remarks>
-    [Experimental("MEAI001")]
+    [Experimental(DiagnosticIds.Experiments.ResponseContinuations, Message = DiagnosticIds.Experiments.ResponseContinuationsMessage, UrlFormat = DiagnosticIds.UrlFormat)]
     [JsonIgnore]
     public ResponseContinuationToken? ContinuationToken { get; set; }
 

src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatResponse.cs

@@ -5,6 +5,7 @@
 using System.Collections.Generic;
 using System.Diagnostics.CodeAnalysis;
 using System.Text.Json.Serialization;
+using Microsoft.Shared.DiagnosticIds;
 using Microsoft.Shared.Diagnostics;
 
 namespace Microsoft.Extensions.AI;
@@ -100,7 +101,7 @@ public IList<ChatMessage> Messages
     /// to poll for completion.
     /// </para>
     /// </remarks>
-    [Experimental("MEAI001")]
+    [Experimental(DiagnosticIds.Experiments.ResponseContinuations, Message = DiagnosticIds.Experiments.ResponseContinuationsMessage, UrlFormat = DiagnosticIds.UrlFormat)]
     [JsonIgnore]
     public ResponseContinuationToken? ContinuationToken { get; set; }
 

src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatResponseUpdate.cs

@@ -6,6 +6,7 @@
 using System.Diagnostics;
 using System.Diagnostics.CodeAnalysis;
 using System.Text.Json.Serialization;
+using Microsoft.Shared.DiagnosticIds;
 
 namespace Microsoft.Extensions.AI;
 
@@ -170,7 +171,7 @@ public IList<AIContent> Contents
     /// to resume streaming from the point of interruption.
     /// </para>
     /// </remarks>
-    [Experimental("MEAI001")]
+    [Experimental(DiagnosticIds.Experiments.ResponseContinuations, Message = DiagnosticIds.Experiments.ResponseContinuationsMessage, UrlFormat = DiagnosticIds.UrlFormat)]
     [JsonIgnore]
     public ResponseContinuationToken? ContinuationToken { get; set; }
 

src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatReduction/IChatReducer.cs

@@ -5,13 +5,14 @@
 using System.Diagnostics.CodeAnalysis;
 using System.Threading;
 using System.Threading.Tasks;
+using Microsoft.Shared.DiagnosticIds;
 
 namespace Microsoft.Extensions.AI;
 
 /// <summary>
 /// Represents a reducer capable of shrinking the size of a list of chat messages.
 /// </summary>
-[Experimental("MEAI001")]
+[Experimental(DiagnosticIds.Experiments.ChatReduction, Message = DiagnosticIds.Experiments.ChatReductionMessage, UrlFormat = DiagnosticIds.UrlFormat)]
 public interface IChatReducer
 {
     /// <summary>Reduces the size of a list of chat messages.</summary>

src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/CodeInterpreterToolCallContent.cs

@@ -3,6 +3,7 @@
 
 using System.Collections.Generic;
 using System.Diagnostics.CodeAnalysis;
+using Microsoft.Shared.DiagnosticIds;
 
 namespace Microsoft.Extensions.AI;
 
@@ -13,7 +14,7 @@ namespace Microsoft.Extensions.AI;
 /// This content type represents when a hosted AI service invokes a code interpreter tool.
 /// It is informational only and represents the call itself, not the result.
 /// </remarks>
-[Experimental("MEAI001")]
+[Experimental(DiagnosticIds.Experiments.CodeInterpreter, Message = DiagnosticIds.Experiments.CodeInterpreterMessage, UrlFormat = DiagnosticIds.UrlFormat)]
 public sealed class CodeInterpreterToolCallContent : AIContent
 {
     /// <summary>

src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/CodeInterpreterToolResultContent.cs

@@ -3,13 +3,14 @@
 
 using System.Collections.Generic;
 using System.Diagnostics.CodeAnalysis;
+using Microsoft.Shared.DiagnosticIds;
 
 namespace Microsoft.Extensions.AI;
 
 /// <summary>
 /// Represents the result of a code interpreter tool invocation by a hosted service.
 /// </summary>
-[Experimental("MEAI001")]
+[Experimental(DiagnosticIds.Experiments.CodeInterpreter, Message = DiagnosticIds.Experiments.CodeInterpreterMessage, UrlFormat = DiagnosticIds.UrlFormat)]
 public sealed class CodeInterpreterToolResultContent : AIContent
 {
     /// <summary>

src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/FunctionApprovalRequestContent.cs

@@ -3,14 +3,15 @@
 
 using System;
 using System.Diagnostics.CodeAnalysis;
+using Microsoft.Shared.DiagnosticIds;
 using Microsoft.Shared.Diagnostics;
 
 namespace Microsoft.Extensions.AI;
 
 /// <summary>
 /// Represents a request for user approval of a function call.
 /// </summary>
-[Experimental("MEAI001")]
+[Experimental(DiagnosticIds.Experiments.FunctionApprovals, Message = DiagnosticIds.Experiments.FunctionApprovalsMessage, UrlFormat = DiagnosticIds.UrlFormat)]
 public sealed class FunctionApprovalRequestContent : UserInputRequestContent
 {
     /// <summary>

src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/FunctionApprovalResponseContent.cs

@@ -3,14 +3,15 @@
 
 using System;
 using System.Diagnostics.CodeAnalysis;
+using Microsoft.Shared.DiagnosticIds;
 using Microsoft.Shared.Diagnostics;
 
 namespace Microsoft.Extensions.AI;
 
 /// <summary>
 /// Represents a response to a function approval request.
 /// </summary>
-[Experimental("MEAI001")]
+[Experimental(DiagnosticIds.Experiments.FunctionApprovals, Message = DiagnosticIds.Experiments.FunctionApprovalsMessage, UrlFormat = DiagnosticIds.UrlFormat)]
 public sealed class FunctionApprovalResponseContent : UserInputResponseContent
 {
     /// <summary>

src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/ImageGenerationToolCallContent.cs

@@ -2,13 +2,14 @@
 // The .NET Foundation licenses this file to you under the MIT license.
 
 using System.Diagnostics.CodeAnalysis;
+using Microsoft.Shared.DiagnosticIds;
 
 namespace Microsoft.Extensions.AI;
 
 /// <summary>
 /// Represents the invocation of an image generation tool call by a hosted service.
 /// </summary>
-[Experimental("MEAI001")]
+[Experimental(DiagnosticIds.Experiments.ImageGeneration, Message = DiagnosticIds.Experiments.ImageGenerationMessage, UrlFormat = DiagnosticIds.UrlFormat)]
 public sealed class ImageGenerationToolCallContent : AIContent
 {
     /// <summary>

src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/ImageGenerationToolResultContent.cs

@@ -3,6 +3,7 @@
 
 using System.Collections.Generic;
 using System.Diagnostics.CodeAnalysis;
+using Microsoft.Shared.DiagnosticIds;
 
 namespace Microsoft.Extensions.AI;
 
@@ -13,7 +14,7 @@ namespace Microsoft.Extensions.AI;
 /// This content type represents when a hosted AI service invokes an image generation tool.
 /// It is informational only and represents the call itself, not the result.
 /// </remarks>
-[Experimental("MEAI001")]
+[Experimental(DiagnosticIds.Experiments.ImageGeneration, Message = DiagnosticIds.Experiments.ImageGenerationMessage, UrlFormat = DiagnosticIds.UrlFormat)]
 public sealed class ImageGenerationToolResultContent : AIContent
 {
     /// <summary>

src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/McpServerToolApprovalRequestContent.cs

@@ -3,14 +3,15 @@
 
 using System;
 using System.Diagnostics.CodeAnalysis;
+using Microsoft.Shared.DiagnosticIds;
 using Microsoft.Shared.Diagnostics;
 
 namespace Microsoft.Extensions.AI;
 
 /// <summary>
 /// Represents a request for user approval of an MCP server tool call.
 /// </summary>
-[Experimental("MEAI001")]
+[Experimental(DiagnosticIds.Experiments.McpServers, Message = DiagnosticIds.Experiments.McpServersMessage, UrlFormat = DiagnosticIds.UrlFormat)]
 public sealed class McpServerToolApprovalRequestContent : UserInputRequestContent
 {
     /// <summary>

src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/McpServerToolApprovalResponseContent.cs

@@ -3,13 +3,14 @@
 
 using System;
 using System.Diagnostics.CodeAnalysis;
+using Microsoft.Shared.DiagnosticIds;
 
 namespace Microsoft.Extensions.AI;
 
 /// <summary>
 /// Represents a response to an MCP server tool approval request.
 /// </summary>
-[Experimental("MEAI001")]
+[Experimental(DiagnosticIds.Experiments.McpServers, Message = DiagnosticIds.Experiments.McpServersMessage, UrlFormat = DiagnosticIds.UrlFormat)]
 public sealed class McpServerToolApprovalResponseContent : UserInputResponseContent
 {
     /// <summary>

src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/McpServerToolCallContent.cs

@@ -4,6 +4,7 @@
 using System;
 using System.Collections.Generic;
 using System.Diagnostics.CodeAnalysis;
+using Microsoft.Shared.DiagnosticIds;
 using Microsoft.Shared.Diagnostics;
 
 namespace Microsoft.Extensions.AI;
@@ -15,7 +16,7 @@ namespace Microsoft.Extensions.AI;
 /// This content type is used to represent an invocation of an MCP server tool by a hosted service.
 /// It is informational only.
 /// </remarks>
-[Experimental("MEAI001")]
+[Experimental(DiagnosticIds.Experiments.McpServers, Message = DiagnosticIds.Experiments.McpServersMessage, UrlFormat = DiagnosticIds.UrlFormat)]
 public sealed class McpServerToolCallContent : AIContent
 {
     /// <summary>

src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/McpServerToolResultContent.cs

@@ -4,6 +4,7 @@
 using System;
 using System.Collections.Generic;
 using System.Diagnostics.CodeAnalysis;
+using Microsoft.Shared.DiagnosticIds;
 using Microsoft.Shared.Diagnostics;
 
 namespace Microsoft.Extensions.AI;
@@ -15,7 +16,7 @@ namespace Microsoft.Extensions.AI;
 /// This content type is used to represent the result of an invocation of an MCP server tool by a hosted service.
 /// It is informational only.
 /// </remarks>
-[Experimental("MEAI001")]
+[Experimental(DiagnosticIds.Experiments.McpServers, Message = DiagnosticIds.Experiments.McpServersMessage, UrlFormat = DiagnosticIds.UrlFormat)]
 public sealed class McpServerToolResultContent : AIContent
 {
     /// <summary>

src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/UserInputRequestContent.cs

@@ -4,14 +4,15 @@
 using System;
 using System.Diagnostics.CodeAnalysis;
 using System.Text.Json.Serialization;
+using Microsoft.Shared.DiagnosticIds;
 using Microsoft.Shared.Diagnostics;
 
 namespace Microsoft.Extensions.AI;
 
 /// <summary>
 /// Represents a request for user input.
 /// </summary>
-[Experimental("MEAI001")]
+[Experimental(DiagnosticIds.Experiments.FunctionApprovals, Message = DiagnosticIds.Experiments.FunctionApprovalsMessage, UrlFormat = DiagnosticIds.UrlFormat)]
 [JsonPolymorphic(TypeDiscriminatorPropertyName = "$type")]
 [JsonDerivedType(typeof(FunctionApprovalRequestContent), "functionApprovalRequest")]
 [JsonDerivedType(typeof(McpServerToolApprovalRequestContent), "mcpServerToolApprovalRequest")]

src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/UserInputResponseContent.cs

@@ -4,14 +4,15 @@
 using System;
 using System.Diagnostics.CodeAnalysis;
 using System.Text.Json.Serialization;
+using Microsoft.Shared.DiagnosticIds;
 using Microsoft.Shared.Diagnostics;
 
 namespace Microsoft.Extensions.AI;
 
 /// <summary>
 /// Represents the response to a request for user input.
 /// </summary>
-[Experimental("MEAI001")]
+[Experimental(DiagnosticIds.Experiments.FunctionApprovals, Message = DiagnosticIds.Experiments.FunctionApprovalsMessage, UrlFormat = DiagnosticIds.UrlFormat)]
 [JsonPolymorphic(TypeDiscriminatorPropertyName = "$type")]
 [JsonDerivedType(typeof(FunctionApprovalResponseContent), "functionApprovalResponse")]
 [JsonDerivedType(typeof(McpServerToolApprovalResponseContent), "mcpServerToolApprovalResponse")]

src/Libraries/Microsoft.Extensions.AI.Abstractions/Functions/ApprovalRequiredAIFunction.cs

@@ -3,6 +3,7 @@
 
 using System;
 using System.Diagnostics.CodeAnalysis;
+using Microsoft.Shared.DiagnosticIds;
 
 namespace Microsoft.Extensions.AI;
 
@@ -14,7 +15,7 @@ namespace Microsoft.Extensions.AI;
 /// This class simply augments an <see cref="AIFunction"/> with an indication that approval is required before invocation.
 /// It does not enforce the requirement for user approval; it is the responsibility of the invoker to obtain that approval before invoking the function.
 /// </remarks>
-[Experimental("MEAI001")]
+[Experimental(DiagnosticIds.Experiments.FunctionApprovals, Message = DiagnosticIds.Experiments.FunctionApprovalsMessage, UrlFormat = DiagnosticIds.UrlFormat)]
 public sealed class ApprovalRequiredAIFunction : DelegatingAIFunction
 {
     /// <summary>

src/Libraries/Microsoft.Extensions.AI.Abstractions/HostedMcpServerToolAlwaysRequireApprovalMode.cs

@@ -3,6 +3,7 @@
 
 using System.Diagnostics;
 using System.Diagnostics.CodeAnalysis;
+using Microsoft.Shared.DiagnosticIds;
 
 namespace Microsoft.Extensions.AI;
 
@@ -12,7 +13,7 @@ namespace Microsoft.Extensions.AI;
 /// <remarks>
 /// Use <see cref="HostedMcpServerToolApprovalMode.AlwaysRequire"/> to get an instance of <see cref="HostedMcpServerToolAlwaysRequireApprovalMode"/>.
 /// </remarks>
-[Experimental("MEAI001")]
+[Experimental(DiagnosticIds.Experiments.McpServers, Message = DiagnosticIds.Experiments.McpServersMessage, UrlFormat = DiagnosticIds.UrlFormat)]
 [DebuggerDisplay(nameof(AlwaysRequire))]
 public sealed class HostedMcpServerToolAlwaysRequireApprovalMode : HostedMcpServerToolApprovalMode
 {

src/Libraries/Microsoft.Extensions.AI.Abstractions/HostedMcpServerToolApprovalMode.cs

@@ -4,6 +4,7 @@
 using System.Collections.Generic;
 using System.Diagnostics.CodeAnalysis;
 using System.Text.Json.Serialization;
+using Microsoft.Shared.DiagnosticIds;
 
 namespace Microsoft.Extensions.AI;
 
@@ -14,7 +15,7 @@ namespace Microsoft.Extensions.AI;
 /// The predefined values <see cref="AlwaysRequire" />, and <see cref="NeverRequire"/> are provided to specify handling for all tools.
 /// To specify approval behavior for individual tool names, use <see cref="RequireSpecific(IList{string}, IList{string})"/>.
 /// </remarks>
-[Experimental("MEAI001")]
+[Experimental(DiagnosticIds.Experiments.McpServers, Message = DiagnosticIds.Experiments.McpServersMessage, UrlFormat = DiagnosticIds.UrlFormat)]
 [JsonPolymorphic(TypeDiscriminatorPropertyName = "$type")]
 [JsonDerivedType(typeof(HostedMcpServerToolNeverRequireApprovalMode), typeDiscriminator: "never")]
 [JsonDerivedType(typeof(HostedMcpServerToolAlwaysRequireApprovalMode), typeDiscriminator: "always")]

src/Libraries/Microsoft.Extensions.AI.Abstractions/HostedMcpServerToolNeverRequireApprovalMode.cs

@@ -3,6 +3,7 @@
 
 using System.Diagnostics;
 using System.Diagnostics.CodeAnalysis;
+using Microsoft.Shared.DiagnosticIds;
 
 namespace Microsoft.Extensions.AI;
 
@@ -12,7 +13,7 @@ namespace Microsoft.Extensions.AI;
 /// <remarks>
 /// Use <see cref="HostedMcpServerToolApprovalMode.NeverRequire"/> to get an instance of <see cref="HostedMcpServerToolNeverRequireApprovalMode"/>.
 /// </remarks>
-[Experimental("MEAI001")]
+[Experimental(DiagnosticIds.Experiments.McpServers, Message = DiagnosticIds.Experiments.McpServersMessage, UrlFormat = DiagnosticIds.UrlFormat)]
 [DebuggerDisplay(nameof(NeverRequire))]
 public sealed class HostedMcpServerToolNeverRequireApprovalMode : HostedMcpServerToolApprovalMode
 {