.NET: Surface downstream experimental flags and remove unnecessary suppressions (#3968)

* Surface downstream experimental flags and remove unecessary suppressions * Fix format error * Fix file encoding. * Address PR comments.
2026-06-16 21:04:09 +08:00 · 2026-02-17 12:53:33 +00:00
parent 54a67d96cd
commit 8015e00f56
22 changed files with 93 additions and 14 deletions
@@ -371,6 +371,10 @@
    <File Path="src/Shared/Demos/README.md" />
    <File Path="src/Shared/Demos/SampleEnvironment.cs" />
  </Folder>
+  <Folder Name="/Solution Items/src/Shared/DiagnosticIds/">
+    <File Path="src/Shared/DiagnosticIds/DiagnosticsIds.cs" />
+    <File Path="src/Shared/DiagnosticIds/README.md" />
+  </Folder>
  <Folder Name="/Solution Items/src/Shared/IntegrationTests/">
    <File Path="src/Shared/IntegrationTests/AnthropicConfiguration.cs" />
    <File Path="src/Shared/IntegrationTests/AzureAIConfiguration.cs" />
@@ -23,4 +23,7 @@
  <ItemGroup Condition="'$(InjectSharedStructuredOutput)' == 'true'">
    <Compile Include="$(MSBuildThisFileDirectory)\..\..\src\Shared\StructuredOutput\*.cs" LinkBase="Shared\StructuredOutput" />
  </ItemGroup>
+  <ItemGroup Condition="'$(InjectSharedDiagnosticIds)' == 'true'">
+    <Compile Include="$(MSBuildThisFileDirectory)\..\..\src\Shared\DiagnosticIds\*.cs" LinkBase="Shared\DiagnosticIds" />
+  </ItemGroup>
 </Project>
@@ -15,7 +15,6 @@
        and cannot access parent folders where Directory.Packages.props resides.
    -->
    <ManagePackageVersionsCentrally>false</ManagePackageVersionsCentrally>
-    <NoWarn>$(NoWarn);MEAI001;OPENAI001</NoWarn>
  </PropertyGroup>

  <!-- 
@@ -1,4 +1,4 @@
-// Copyright (c) Microsoft. All rights reserved.
+// Copyright (c) Microsoft. All rights reserved.

 #if !NET8_0_OR_GREATER

@@ -28,7 +28,7 @@ internal sealed class ExperimentalAttribute : Attribute
    /// <param name="diagnosticId">Human readable explanation for marking experimental API.</param>
    public ExperimentalAttribute(string diagnosticId)
    {
-        DiagnosticId = diagnosticId;
+        this.DiagnosticId = diagnosticId;
    }

    /// <summary>
@@ -5,6 +5,7 @@ using System.Collections.Generic;
 using System.Diagnostics.CodeAnalysis;
 using System.Text.Json.Serialization;
 using Microsoft.Extensions.AI;
+using Microsoft.Shared.DiagnosticIds;
 using Microsoft.Shared.Diagnostics;

 namespace Microsoft.Agents.AI;
@@ -173,6 +174,7 @@ public class AgentResponse
    /// to poll for completion.
    /// </para>
    /// </remarks>
+    [Experimental(DiagnosticIds.Experiments.AIResponseContinuations)]
    public ResponseContinuationToken? ContinuationToken { get; set; }

    /// <summary>
@@ -1,7 +1,9 @@
 // Copyright (c) Microsoft. All rights reserved.

 using System;
+using System.Diagnostics.CodeAnalysis;
 using Microsoft.Extensions.AI;
+using Microsoft.Shared.DiagnosticIds;
 using Microsoft.Shared.Diagnostics;

 namespace Microsoft.Agents.AI;
@@ -50,6 +52,7 @@ public class AgentRunOptions
    /// can be polled for completion by obtaining the token from the <see cref="AgentResponse.ContinuationToken"/> property
    /// and passing it via this property on subsequent calls to <see cref="AIAgent.RunAsync(AgentSession?, AgentRunOptions?, System.Threading.CancellationToken)"/>.
    /// </remarks>
+    [Experimental(DiagnosticIds.Experiments.AIResponseContinuations)]
    public ResponseContinuationToken? ContinuationToken { get; set; }

    /// <summary>
@@ -14,6 +14,8 @@
    <InjectIsExternalInitOnLegacy>true</InjectIsExternalInitOnLegacy>
    <InjectRequiredMemberOnLegacy>true</InjectRequiredMemberOnLegacy>
    <InjectCompilerFeatureRequiredOnLegacy>true</InjectCompilerFeatureRequiredOnLegacy>
+    <InjectExperimentalAttributeOnLegacy>true</InjectExperimentalAttributeOnLegacy>
+    <InjectSharedDiagnosticIds>true</InjectSharedDiagnosticIds>
  </PropertyGroup>

  <Import Project="$(RepoRoot)/dotnet/nuget/nuget-package.props" />
@@ -1,20 +1,21 @@
 // Copyright (c) Microsoft. All rights reserved.

+using System.Diagnostics.CodeAnalysis;
 using System.Runtime.CompilerServices;
 using Azure.AI.Projects;
 using Azure.AI.Projects.OpenAI;
 using Microsoft.Extensions.AI;
+using Microsoft.Shared.DiagnosticIds;
 using Microsoft.Shared.Diagnostics;
 using OpenAI.Responses;

-#pragma warning disable OPENAI001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
-
 namespace Microsoft.Agents.AI.AzureAI;

 /// <summary>
 /// Provides a chat client implementation that integrates with Azure AI Agents, enabling chat interactions using
 /// Azure-specific agent capabilities.
 /// </summary>
+[Experimental(DiagnosticIds.Experiments.AIOpenAIResponses)]
 internal sealed class AzureAIProjectChatClient : DelegatingChatClient
 {
    private readonly ChatClientMetadata? _metadata;
@@ -2,6 +2,7 @@

 using System.ClientModel;
 using System.ClientModel.Primitives;
+using System.Diagnostics.CodeAnalysis;
 using System.Runtime.CompilerServices;
 using System.Text;
 using System.Text.Json;
@@ -12,18 +13,17 @@ using Azure.AI.Projects.OpenAI;
 using Microsoft.Agents.AI;
 using Microsoft.Agents.AI.AzureAI;
 using Microsoft.Extensions.AI;
+using Microsoft.Shared.DiagnosticIds;
 using Microsoft.Shared.Diagnostics;
 using OpenAI;
 using OpenAI.Responses;

-#pragma warning disable MEAI001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
-#pragma warning disable OPENAI001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
-
 namespace Azure.AI.Projects;

 /// <summary>
 /// Provides extension methods for <see cref="AIProjectClient"/>.
 /// </summary>
+[Experimental(DiagnosticIds.Experiments.AIOpenAIResponses)]
 public static partial class AzureAIProjectChatClientExtensions
 {
    /// <summary>
@@ -8,6 +8,11 @@

  <Import Project="$(RepoRoot)/dotnet/nuget/nuget-package.props" />

+  <PropertyGroup>
+    <InjectExperimentalAttributeOnLegacy>true</InjectExperimentalAttributeOnLegacy>
+    <InjectSharedDiagnosticIds>true</InjectSharedDiagnosticIds>
+  </PropertyGroup>
+
  <ItemGroup>
    <PackageReference Include="Azure.AI.Projects" />
    <PackageReference Include="Azure.AI.Projects.OpenAI" />
@@ -3,7 +3,6 @@
  <PropertyGroup>
    <TargetFrameworks>$(TargetFrameworksCore)</TargetFrameworks>
    <RootNamespace>Microsoft.Agents.AI</RootNamespace>
-    <NoWarn>$(NoWarn);MEAI001</NoWarn>
    <VersionSuffix>preview</VersionSuffix>
  </PropertyGroup>

@@ -4,8 +4,7 @@
    <TargetFrameworks>$(TargetFrameworksCore)</TargetFrameworks>
    <ImplicitUsings>enable</ImplicitUsings>
    <!-- CA2007: This rule should generally be suppressed in Durable Task libraries -->
-    <!-- MEAI001: UserInputRequestContent is experimental but used in source-generated code for AgentResponse -->
-    <NoWarn>$(NoWarn);CA2007;MEAI001</NoWarn>
+    <NoWarn>$(NoWarn);CA2007</NoWarn>
  </PropertyGroup>

  <Import Project="$(RepoRoot)/dotnet/nuget/nuget-package.props" />
@@ -2,7 +2,7 @@

  <PropertyGroup>
    <TargetFrameworks>$(TargetFrameworksCore)</TargetFrameworks>
-    <NoWarn>$(NoWarn);OPENAI001;MEAI001</NoWarn>
+    <NoWarn>$(NoWarn);MEAI001</NoWarn>
    <RootNamespace>Microsoft.Agents.AI.Hosting.OpenAI</RootNamespace>
    <VersionSuffix>alpha</VersionSuffix>
    <InterceptorsNamespaces>$(InterceptorsNamespaces);Microsoft.AspNetCore.Http.Generated</InterceptorsNamespaces>
@@ -1,10 +1,13 @@
 // Copyright (c) Microsoft. All rights reserved.

 using System.ClientModel;
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Shared.DiagnosticIds;
 using OpenAI.Responses;

 namespace Microsoft.Agents.AI.OpenAI;

+[Experimental(DiagnosticIds.Experiments.AIOpenAIResponses)]
 internal sealed class AsyncStreamingResponseUpdateCollectionResult : AsyncCollectionResult<StreamingResponseUpdate>
 {
    private readonly IAsyncEnumerable<AgentResponseUpdate> _updates;
@@ -1,7 +1,9 @@
 // Copyright (c) Microsoft. All rights reserved.

 using System.ClientModel;
+using System.Diagnostics.CodeAnalysis;
 using Microsoft.Agents.AI.OpenAI;
+using Microsoft.Shared.DiagnosticIds;
 using Microsoft.Shared.Diagnostics;
 using OpenAI.Chat;
 using OpenAI.Responses;
@@ -18,6 +20,7 @@ namespace Microsoft.Agents.AI;
 /// The methods handle the conversion between OpenAI chat message types and Microsoft Extensions AI types,
 /// and return OpenAI <see cref="ChatCompletion"/> objects directly from the agent's <see cref="AgentResponse"/>.
 /// </remarks>
+[Experimental(DiagnosticIds.Experiments.AIOpenAIResponses)]
 public static class AIAgentWithOpenAIExtensions
 {
    /// <summary>
@@ -1,6 +1,8 @@
 // Copyright (c) Microsoft. All rights reserved.

+using System.Diagnostics.CodeAnalysis;
 using Microsoft.Agents.AI;
+using Microsoft.Shared.DiagnosticIds;
 using Microsoft.Shared.Diagnostics;
 using OpenAI.Chat;
 using OpenAI.Responses;
@@ -11,6 +13,7 @@ namespace Microsoft.Agents.AI;
 /// Provides extension methods for <see cref="AgentResponse"/> and <see cref="AgentResponseUpdate"/> instances to
 /// create or extract native OpenAI response objects from the Microsoft Agent Framework responses.
 /// </summary>
+[Experimental(DiagnosticIds.Experiments.AIOpenAIResponses)]
 public static class AgentResponseExtensions
 {
    /// <summary>
@@ -1,9 +1,11 @@
 // Copyright (c) Microsoft. All rights reserved.

 using System.ClientModel;
+using System.Diagnostics.CodeAnalysis;
 using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
 using Microsoft.Extensions.Logging;
+using Microsoft.Shared.DiagnosticIds;
 using Microsoft.Shared.Diagnostics;

 namespace OpenAI.Assistants;
@@ -18,6 +20,7 @@ namespace OpenAI.Assistants;
 /// The methods handle the conversion from OpenAI clients to <see cref="IChatClient"/> instances and then wrap them
 /// in <see cref="ChatClientAgent"/> objects that implement the <see cref="AIAgent"/> interface.
 /// </remarks>
+[Experimental(DiagnosticIds.Experiments.AIOpenAIAssistants)]
 public static class OpenAIAssistantClientExtensions
 {
    /// <summary>
@@ -1,8 +1,10 @@
 // Copyright (c) Microsoft. All rights reserved.

+using System.Diagnostics.CodeAnalysis;
 using Microsoft.Agents.AI;
 using Microsoft.Extensions.AI;
 using Microsoft.Extensions.Logging;
+using Microsoft.Shared.DiagnosticIds;
 using Microsoft.Shared.Diagnostics;

 namespace OpenAI.Responses;
@@ -17,6 +19,7 @@ namespace OpenAI.Responses;
 /// The methods handle the conversion from OpenAI clients to <see cref="IChatClient"/> instances and then wrap them
 /// in <see cref="ChatClientAgent"/> objects that implement the <see cref="AIAgent"/> interface.
 /// </remarks>
+[Experimental(DiagnosticIds.Experiments.AIOpenAIResponses)]
 public static class OpenAIResponseClientExtensions
 {
    /// <summary>
@@ -2,13 +2,17 @@

  <PropertyGroup>
    <VersionSuffix>preview</VersionSuffix>
-    <NoWarn>$(NoWarn);OPENAI001;</NoWarn>
    <ImplicitUsings>enable</ImplicitUsings>
    <InjectSharedThrow>true</InjectSharedThrow>
  </PropertyGroup>

  <Import Project="$(RepoRoot)/dotnet/nuget/nuget-package.props" />

+  <PropertyGroup>
+    <InjectExperimentalAttributeOnLegacy>true</InjectExperimentalAttributeOnLegacy>
+    <InjectSharedDiagnosticIds>true</InjectSharedDiagnosticIds>
+  </PropertyGroup>
+
  <ItemGroup>
    <PackageReference Include="Microsoft.Extensions.AI.OpenAI" />
  </ItemGroup>
@@ -0,0 +1,33 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace Microsoft.Shared.DiagnosticIds;
+
+/// <summary>
+///  Various diagnostic IDs reported by this repo.
+/// </summary>
+internal static class DiagnosticIds
+{
+    /// <summary>
+    ///  Experiments supported by this repo.
+    /// </summary>
+    internal static class Experiments
+    {
+        // This experiment ID is used for all experimental features in the Microsoft Agent Framework.
+        internal const string AgentsAIExperiments = "MAAI001";
+
+        // These diagnostic IDs are defined by the MEAI package for its experimental APIs.
+        // We use the same IDs so consumers do not need to suppress additional diagnostics
+        // when using the experimental MEAI APIs.
+        internal const string AIResponseContinuations = MEAIExperiments;
+        internal const string AIMcpServers = MEAIExperiments;
+        internal const string AIFunctionApprovals = MEAIExperiments;
+
+        // These diagnostic IDs are defined by the OpenAI package for its experimental APIs.
+        // We use the same IDs so consumers do not need to suppress additional diagnostics
+        // when using the experimental OpenAI APIs.
+        internal const string AIOpenAIResponses = "OPENAI001";
+        internal const string AIOpenAIAssistants = "OPENAI001";
+
+        private const string MEAIExperiments = "MEAI001";
+    }
+}
@@ -0,0 +1,11 @@
+# Diagnostic IDs
+
+Defines various diagnostic IDs reported by this repo.
+
+To use this in your project, add the following to your `.csproj` file:
+
+```xml
+<PropertyGroup>
+  <InjectSharedDiagnosticIds>true</InjectSharedDiagnosticIds>
+</PropertyGroup>
+```
@@ -2,7 +2,6 @@

  <PropertyGroup>
    <TargetFrameworks>net10.0;net9.0</TargetFrameworks>
-    <NoWarn>$(NoWarn);MEAI001</NoWarn>
  </PropertyGroup>

  <PropertyGroup Condition="$([MSBuild]::IsTargetFrameworkCompatible('$(TargetFramework)', 'net8.0'))">