dotnet
Inventory MEAI001 experimental APIs into feature-specific diagnostic IDs (MEAI0001-MEAI0008)
This PR inventories all APIs marked as [Experimental("MEAI001")] and groups them by feature, assigning each group a specific diagnostic ID. The diagnostic IDs are defined in the shared DiagnosticIds.cs file, and all experimental API attributes have been updated to reference these constants.
Changes Made
MEAI Experimental Attributes
- Updated all MEAI experimental attributes to use feature-specific diagnostic IDs
- Format:
[Experimental(DiagnosticIds.Experiments.*, UrlFormat = DiagnosticIds.UrlFormat)]
Project Files
- Removed obsolete
MEAI001suppression from all project files (replaced with granular MEAI0001-MEAI0008)
Documentation
- Added MEAI0001-MEAI0008 entries to
docs/list-of-diagnostics.md
Diagnostic ID Assignments
MEAI0001 - Image Generation
Microsoft.Extensions.AI.IImageGeneratorMicrosoft.Extensions.AI.DelegatingImageGeneratorMicrosoft.Extensions.AI.ImageGenerationOptionsMicrosoft.Extensions.AI.ImageGenerationResponseFormatMicrosoft.Extensions.AI.ImageGenerationRequestMicrosoft.Extensions.AI.ImageGenerationResponseMicrosoft.Extensions.AI.ImageGeneratorExtensionsMicrosoft.Extensions.AI.ImageGeneratorMetadataMicrosoft.Extensions.AI.ImageGenerationToolCallContentMicrosoft.Extensions.AI.ImageGenerationToolResultContentMicrosoft.Extensions.AI.HostedImageGenerationToolMicrosoft.Extensions.AI.ImageGeneratingChatClientMicrosoft.Extensions.AI.ImageGeneratingChatClientBuilderExtensionsMicrosoft.Extensions.AI.OpenTelemetryImageGeneratorMicrosoft.Extensions.AI.OpenTelemetryImageGeneratorBuilderExtensionsMicrosoft.Extensions.AI.ConfigureOptionsImageGeneratorMicrosoft.Extensions.AI.ConfigureOptionsImageGeneratorBuilderExtensionsMicrosoft.Extensions.AI.ImageGeneratorBuilderMicrosoft.Extensions.AI.ImageGeneratorBuilderImageGeneratorExtensionsMicrosoft.Extensions.AI.LoggingImageGeneratorMicrosoft.Extensions.AI.LoggingImageGeneratorBuilderExtensionsMicrosoft.Extensions.DependencyInjection.ImageGeneratorBuilderServiceCollectionExtensionsMicrosoft.Extensions.AI.OpenAIClientExtensions.AsIImageGenerator(extension method)
MEAI0002 - Speech to Text
Microsoft.Extensions.AI.ISpeechToTextClientMicrosoft.Extensions.AI.DelegatingSpeechToTextClientMicrosoft.Extensions.AI.SpeechToTextOptionsMicrosoft.Extensions.AI.SpeechToTextResponseMicrosoft.Extensions.AI.SpeechToTextResponseUpdateMicrosoft.Extensions.AI.SpeechToTextResponseUpdateKindMicrosoft.Extensions.AI.SpeechToTextResponseUpdateExtensionsMicrosoft.Extensions.AI.SpeechToTextClientExtensionsMicrosoft.Extensions.AI.SpeechToTextClientMetadataMicrosoft.Extensions.AI.OpenAISpeechToTextClientMicrosoft.Extensions.AI.SpeechToTextClientBuilderMicrosoft.Extensions.AI.SpeechToTextClientBuilderSpeechToTextClientExtensionsMicrosoft.Extensions.AI.ConfigureOptionsSpeechToTextClientMicrosoft.Extensions.AI.ConfigureOptionsSpeechToTextClientBuilderExtensionsMicrosoft.Extensions.AI.LoggingSpeechToTextClientMicrosoft.Extensions.AI.LoggingSpeechToTextClientBuilderExtensionsMicrosoft.Extensions.AI.OpenTelemetrySpeechToTextClientMicrosoft.Extensions.AI.OpenTelemetrySpeechToTextClientBuilderExtensionsMicrosoft.Extensions.DependencyInjection.SpeechToTextClientBuilderServiceCollectionExtensionsMicrosoft.Extensions.AI.OpenAIClientExtensions.AsISpeechToTextClient(extension method)
MEAI0003 - MCP Servers
Microsoft.Extensions.AI.HostedMcpServerToolMicrosoft.Extensions.AI.HostedMcpServerToolApprovalModeMicrosoft.Extensions.AI.HostedMcpServerToolAlwaysRequireApprovalModeMicrosoft.Extensions.AI.HostedMcpServerToolNeverRequireApprovalModeMicrosoft.Extensions.AI.HostedMcpServerToolRequireSpecificApprovalModeMicrosoft.Extensions.AI.McpServerToolCallContentMicrosoft.Extensions.AI.McpServerToolResultContentMicrosoft.Extensions.AI.McpServerToolApprovalRequestContentMicrosoft.Extensions.AI.McpServerToolApprovalResponseContent
MEAI0004 - Function Approvals
Microsoft.Extensions.AI.ApprovalRequiredAIFunctionMicrosoft.Extensions.AI.FunctionApprovalRequestContentMicrosoft.Extensions.AI.FunctionApprovalResponseContentMicrosoft.Extensions.AI.UserInputRequestContentMicrosoft.Extensions.AI.UserInputResponseContent
MEAI0005 - Tool Reduction
Microsoft.Extensions.AI.IToolReductionStrategyMicrosoft.Extensions.AI.ToolReducingChatClientMicrosoft.Extensions.AI.ChatClientBuilderToolReductionExtensionsMicrosoft.Extensions.AI.EmbeddingToolReductionStrategy
MEAI0006 - Chat Reduction
Microsoft.Extensions.AI.IChatReducerMicrosoft.Extensions.AI.MessageCountingChatReducerMicrosoft.Extensions.AI.SummarizingChatReducerMicrosoft.Extensions.AI.ReducingChatClientMicrosoft.Extensions.AI.ReducingChatClientBuilderExtensions
MEAI0007 - Response Continuations
Microsoft.Extensions.AI.ResponseContinuationTokenMicrosoft.Extensions.AI.ChatOptions.AllowBackgroundResponses(property)Microsoft.Extensions.AI.ChatOptions.ContinuationToken(property)Microsoft.Extensions.AI.ChatResponse.ContinuationToken(property)Microsoft.Extensions.AI.ChatResponseUpdate.ContinuationToken(property)
MEAI0008 - Code Interpreter
Microsoft.Extensions.AI.CodeInterpreterToolCallContentMicrosoft.Extensions.AI.CodeInterpreterToolResultContent
microsoft/agent-framework Usage
Function Approvals (MEAI0004) is used in agent-framework samples:
✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.
@copilot Instead of a truncated Description column, update the PR description to provide a complete list of all fully-qualified APIs included in each of the Diagnostic ID Assignments. This is important as it will help us find callers of these APIs more easily.
@copilot Instead of a truncated Description column, update the PR description to provide a complete list of all fully-qualified APIs included in each of the Diagnostic ID Assignments. This is importan...
Updated the PR description with complete fully-qualified API names for all 8 diagnostic ID groups, including types (classes, interfaces, structs, enums), extension methods, and property-level experimental attributes.
@stephentoub / @JeremyLikness / @jozkee / @ericstj / @MackinnonBuck - I recommend we break out experimental APIs up into granular diagnostics in this manner in preparation for moving some APIs out of experimental mode. That will ensure consumers have targeted suppressions and we can discover which experimental APIs are being referenced more easily.
For planning the downstream effects of this and to scout out if any of our experimental APIs are perhaps ready to be stable, I searched through Agent Framework and found the following to be in use.
| Symbol | Status |
|---|---|
| ☑️ | In use |
| ✖️ | Not in use, but related APIs are |
| ❌ | Not in use |
- ❌ MEAI0001 - Image Generation
- ❌ MEAI0002 - Speech to Text
- ☑️ MEAI0003 - MCP Servers
- ☑️
Microsoft.Extensions.AI.HostedMcpServerTool - ☑️
Microsoft.Extensions.AI.HostedMcpServerToolApprovalMode - ☑️
Microsoft.Extensions.AI.HostedMcpServerToolAlwaysRequireApprovalMode - ☑️
Microsoft.Extensions.AI.HostedMcpServerToolNeverRequireApprovalMode - ☑️
Microsoft.Extensions.AI.HostedMcpServerToolRequireSpecificApprovalMode - ✖️
Microsoft.Extensions.AI.McpServerToolCallContent - ✖️
Microsoft.Extensions.AI.McpServerToolResultContent - ☑️
Microsoft.Extensions.AI.McpServerToolApprovalRequestContent - ✖️
Microsoft.Extensions.AI.McpServerToolApprovalResponseContent
- ☑️
- ☑️ MEAI0004 - Function Approvals
- ✖️
Microsoft.Extensions.AI.ApprovalRequiredAIFunction - ☑️
Microsoft.Extensions.AI.FunctionApprovalRequestContent - ☑️
Microsoft.Extensions.AI.FunctionApprovalResponseContent - ☑️
Microsoft.Extensions.AI.UserInputRequestContent - ✖️
Microsoft.Extensions.AI.UserInputResponseContent
- ✖️
- ❌ MEAI0005 - Tool Reduction
- ☑️ MEAI0006 - Chat Reduction
- ☑️
Microsoft.Extensions.AI.IChatReducer - ✖️
Microsoft.Extensions.AI.MessageCountingChatReducer - ✖️
Microsoft.Extensions.AI.SummarizingChatReducer - ✖️
Microsoft.Extensions.AI.ReducingChatClient - ✖️
Microsoft.Extensions.AI.ReducingChatClientBuilderExtensions
- ☑️
- ☑️ MEAI0007 - Response Continuations
- ☑️
Microsoft.Extensions.AI.ResponseContinuationToken - ☑️
Microsoft.Extensions.AI.ChatOptions.AllowBackgroundResponses(property) - ☑️
Microsoft.Extensions.AI.ChatOptions.ContinuationToken(property) - ☑️
Microsoft.Extensions.AI.ChatResponse.ContinuationToken(property) - ☑️
Microsoft.Extensions.AI.ChatResponseUpdate.ContinuationToken(property)
- ☑️
- ❌ MEAI0008 - Code Interpreter
Using Agent Framework's consumption as a litmus test for an experimental API being ready to be marked as stable, I recommend we follow this PR with the following efforts:
- Finish the active MCP Server work, conduct an API review of those APIs, and mark all APIs in MEAI0004 as stable, retiring that diagnostic
- Mark
IChatReduceras stable while leaving all of the implementations as[Experimental] - Review the APIs for Response Continuations, mark them all as stable, and retire that diagnostic
- Leave the Image Generation, Speech to Text, Tool Reduction, and Code Interpreter APIs as
[Experimental].
@copilot There are build errors in Microsoft.AspNetCore.Diagnostics.Middleware because ExperimentalAttribute is found in 2 of its assembly references:
The type 'ExperimentalAttribute' exists in both 'Microsoft.Extensions.Telemetry, Version=10.2.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35' and 'System.Runtime, Version=9.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a'
I believe that if the ExperimentalAttribute is injected into the Microsoft.AspNetCore.Diagnostics.Middleware project as well, that would cause references to it to be resolved from the internal attribute, forcing a disambiguation and resolving the build error.
@copilot There are build errors in Microsoft.AspNetCore.Diagnostics.Middleware because
ExperimentalAttributeis found in 2 of its assembly references:The type 'ExperimentalAttribute' exists in b...
Added InjectExperimentalAttributeOnLegacy=true and CS0436 suppression to Microsoft.AspNetCore.Diagnostics.Middleware.csproj in 30a7d72. This injects the internal ExperimentalAttribute polyfill, resolving the type ambiguity between Microsoft.Extensions.Telemetry and System.Runtime.
@copilot Additional projects are failing for the ambiguous ExperimentalAttribute problem. It might be best to inject the attribute into all projects. But we can start with the next batch of failures:
- Microsoft.AspNetCore.Testing
- Microsoft.Extensions.Compliance.Abstractions
- Microsoft.Extensions.AmbientMetadata.Build
@copilot Additional projects are failing for the ambiguous ExperimentalAttribute problem. It might be best to inject the attribute into all projects. But we can start with the next batch of failures: ...
Added CS0436 suppression to the three projects in 6f6a6b8. They already had InjectExperimentalAttributeOnLegacy=true but were missing the warning suppression needed to allow the internal polyfill to override the BCL type.
@copilot The error is happening in more projects. We should probably just guard against it in all projects across the solution using the Directory.Build.props files.
Example:
##[error]artifacts\obj\Microsoft.Extensions.Diagnostics.Probes\Release\net9.0\Microsoft.Extensions.Diagnostics.Probes.AssemblyInfo.cs(13,44): error CS0436: (NETCORE_ENGINEERING_TELEMETRY=Build) The type 'ExperimentalAttribute' in 'D:\a_work\1\s\eng\MSBuild....\src\LegacySupport\ExperimentalAttribute\ExperimentalAttribute.cs' conflicts with the imported type 'ExperimentalAttribute' in 'System.Runtime, Version=9.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a'. Using the type defined in 'D:\a_work\1\s\eng\MSBuild....\src\LegacySupport\ExperimentalAttribute\ExperimentalAttribute.cs'.
@copilot The error is happening in more projects. We should probably just guard against it in all projects across the solution using the Directory.Build.props files.
Example: ...
Moved the CS0436 suppression to LegacySupport.props for central handling in fe76059. The suppression is now automatically applied to all projects that use InjectExperimentalAttributeOnLegacy=true when targeting net8.0 or net9.0, eliminating the need for individual project-level suppressions.
@jeffhandley, why are we changing diagnostic id's? For all existing users, this only serves to introduce friction, as existing suppression will break for no benefit. And for new consumption, folks are going to need to suppress many diagnostics where previously they'd only need to suppress one. What benefit do we think we're providing by going more fine-grained here?
Using Agent Framework's consumption as a litmus test for an experimental API being ready to be marked as stab
I am not so sure Agent Framework usage is the only litmus test. That's just a single product using the API - a project which might even have a high tolerance for pain or only use a subset of the API surface. There are plenty of APIs we create that might not be designed for Agent Framework usage. We might have serious flaws in the surface area that Agent Framework happens not to use.
I think we need a better measure of usage/ship-readiness. We can look at NuGet ecosystem usage + internal usage + feedback signal (any signal - issues, blog engagement, docs view counts) + time available + adoption in 3rd party providers (when applicable).
