AddAIContentType automatically registers the content type against every base in the inheritance chain up to AIContent (#7358)

* Initial plan

* Make AddAIContentType with baseType parameter public

Add two new public overloads of AddAIContentType that accept a baseType
parameter, allowing consumers to register AIContent-derived types in
custom polymorphic hierarchies (e.g., under ToolCallContent or
ToolResultContent, not just AIContent).

- Generic: AddAIContentType<TContent>(options, baseType, discriminatorId)
- Non-generic: AddAIContentType(options, baseType, contentType, discriminatorId)

Updates API baseline and adds comprehensive unit tests.

Co-authored-by: jozkee <16040868+jozkee@users.noreply.github.com>

* Auto-register AddAIContentType across full inheritance chain

Instead of adding new baseType overloads, modify the existing
AddAIContentType methods to automatically walk the inheritance
chain from the content type up to AIContent, registering against
every intermediate base type. This eliminates the need for callers
to manually register against each level in the hierarchy.

The internal registration of experimental types (CodeInterpreter,
ImageGeneration) is simplified from 8 calls to 4, since the chain
walker handles intermediate bases (ToolCallContent/ToolResultContent)
automatically.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Add CHANGELOG entry for AddAIContentType chain registration

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Augment tests

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: jozkee <16040868+jozkee@users.noreply.github.com>
Co-authored-by: David Cantu <dacantu@microsoft.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: 3 people

src/Libraries/Microsoft.Extensions.AI.Abstractions/CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## NOT YET RELEASED
 
+- `AddAIContentType` now automatically registers the content type against every base in the inheritance chain up to `AIContent`.
 - Added `IHostedFileClient` interface and related types for interacting with files hosted by the service.
 - Added `WebSearchToolCallContent` and `WebSearchToolResultContent` for representing web search tool calls and results.
 - Added `ToolCallContent` and `ToolResultContent` base classes.

src/Libraries/Microsoft.Extensions.AI.Abstractions/Utilities/AIJsonUtilities.Defaults.cs

@@ -51,20 +51,12 @@ private static JsonSerializerOptions CreateDefaultOptions()
         // Temporary workaround: these types are [Experimental] and can't be added as [JsonDerivedType] on AIContent yet,
         // or else consuming assemblies that used source generation with AIContent would implicitly reference them.
         // Once they're no longer [Experimental] and added as [JsonDerivedType] on AIContent, these lines should be removed.
-        AddAIContentType(options, typeof(AIContent), typeof(CodeInterpreterToolCallContent), typeDiscriminatorId: "codeInterpreterToolCall", checkBuiltIn: false);
-        AddAIContentType(options, typeof(AIContent), typeof(CodeInterpreterToolResultContent), typeDiscriminatorId: "codeInterpreterToolResult", checkBuiltIn: false);
-        AddAIContentType(options, typeof(AIContent), typeof(ImageGenerationToolCallContent), typeDiscriminatorId: "imageGenerationToolCall", checkBuiltIn: false);
-        AddAIContentType(options, typeof(AIContent), typeof(ImageGenerationToolResultContent), typeDiscriminatorId: "imageGenerationToolResult", checkBuiltIn: false);
-        AddAIContentType(options, typeof(AIContent), typeof(WebSearchToolCallContent), typeDiscriminatorId: "webSearchToolCall", checkBuiltIn: false);
-        AddAIContentType(options, typeof(AIContent), typeof(WebSearchToolResultContent), typeDiscriminatorId: "webSearchToolResult", checkBuiltIn: false);
-
-        // Also register the experimental types as derived types of ToolCallContent/ToolResultContent.
-        AddAIContentType(options, typeof(ToolCallContent), typeof(CodeInterpreterToolCallContent), "codeInterpreterToolCall", checkBuiltIn: false);
-        AddAIContentType(options, typeof(ToolCallContent), typeof(ImageGenerationToolCallContent), "imageGenerationToolCall", checkBuiltIn: false);
-        AddAIContentType(options, typeof(ToolCallContent), typeof(WebSearchToolCallContent), "webSearchToolCall", checkBuiltIn: false);
-        AddAIContentType(options, typeof(ToolResultContent), typeof(CodeInterpreterToolResultContent), "codeInterpreterToolResult", checkBuiltIn: false);
-        AddAIContentType(options, typeof(ToolResultContent), typeof(ImageGenerationToolResultContent), "imageGenerationToolResult", checkBuiltIn: false);
-        AddAIContentType(options, typeof(ToolResultContent), typeof(WebSearchToolResultContent), "webSearchToolResult", checkBuiltIn: false);
+        AddAIContentTypeChain(options, typeof(CodeInterpreterToolCallContent), typeDiscriminatorId: "codeInterpreterToolCall", checkBuiltIn: false);
+        AddAIContentTypeChain(options, typeof(CodeInterpreterToolResultContent), typeDiscriminatorId: "codeInterpreterToolResult", checkBuiltIn: false);
+        AddAIContentTypeChain(options, typeof(ImageGenerationToolCallContent), typeDiscriminatorId: "imageGenerationToolCall", checkBuiltIn: false);
+        AddAIContentTypeChain(options, typeof(ImageGenerationToolResultContent), typeDiscriminatorId: "imageGenerationToolResult", checkBuiltIn: false);
+        AddAIContentTypeChain(options, typeof(WebSearchToolCallContent), typeDiscriminatorId: "webSearchToolCall", checkBuiltIn: false);
+        AddAIContentTypeChain(options, typeof(WebSearchToolResultContent), typeDiscriminatorId: "webSearchToolResult", checkBuiltIn: false);
 
         if (JsonSerializer.IsReflectionEnabledByDefault)
         {

src/Libraries/Microsoft.Extensions.AI.Abstractions/Utilities/AIJsonUtilities.cs

@@ -36,7 +36,7 @@ public static void AddAIContentType<TContent>(this JsonSerializerOptions options
         _ = Throw.IfNull(options);
         _ = Throw.IfNull(typeDiscriminatorId);
 
-        AddAIContentType(options, typeof(AIContent), typeof(TContent), typeDiscriminatorId, checkBuiltIn: true);
+        AddAIContentTypeChain(options, typeof(TContent), typeDiscriminatorId, checkBuiltIn: true);
     }
 
     /// <summary>
@@ -46,7 +46,7 @@ public static void AddAIContentType<TContent>(this JsonSerializerOptions options
     /// <param name="contentType">The custom content type to configure.</param>
     /// <param name="typeDiscriminatorId">The type discriminator id for the content type.</param>
     /// <exception cref="ArgumentNullException"><paramref name="options"/>, <paramref name="contentType"/>, or <paramref name="typeDiscriminatorId"/> is <see langword="null"/>.</exception>
-    /// <exception cref="ArgumentException"><paramref name="contentType"/> is a built-in content type or does not derived from <see cref="AIContent"/>.</exception>
+    /// <exception cref="ArgumentException"><paramref name="contentType"/> is a built-in content type or does not derive from <see cref="AIContent"/>.</exception>
     /// <exception cref="InvalidOperationException"><paramref name="options"/> is a read-only instance.</exception>
     public static void AddAIContentType(this JsonSerializerOptions options, Type contentType, string typeDiscriminatorId)
     {
@@ -59,7 +59,7 @@ public static void AddAIContentType(this JsonSerializerOptions options, Type con
             Throw.ArgumentException(nameof(contentType), $"The content type must derive from {nameof(AIContent)}.");
         }
 
-        AddAIContentType(options, typeof(AIContent), contentType, typeDiscriminatorId, checkBuiltIn: true);
+        AddAIContentTypeChain(options, contentType, typeDiscriminatorId, checkBuiltIn: true);
     }
 
     /// <summary>Serializes the supplied values and computes a string hash of the resulting JSON.</summary>
@@ -186,21 +186,35 @@ static void NormalizeJsonNode(JsonNode? node)
         }
     }
 
-    private static void AddAIContentType(JsonSerializerOptions options, Type baseType, Type contentType, string typeDiscriminatorId, bool checkBuiltIn)
+    /// <summary>
+    /// Walks the inheritance chain from <paramref name="contentType"/> up to and including <see cref="AIContent"/>,
+    /// registering the content type as a derived type of each base in the chain.
+    /// </summary>
+    private static void AddAIContentTypeChain(JsonSerializerOptions options, Type contentType, string typeDiscriminatorId, bool checkBuiltIn)
     {
         if (checkBuiltIn && (contentType.Assembly == typeof(AIContent).Assembly))
         {
             Throw.ArgumentException(nameof(contentType), $"Cannot register built-in {nameof(AIContent)} types.");
         }
 
-        IJsonTypeInfoResolver resolver = options.TypeInfoResolver ?? DefaultOptions.TypeInfoResolver!;
-        options.TypeInfoResolver = resolver.WithAddedModifier(typeInfo =>
+        for (Type? baseType = contentType.BaseType;
+             baseType is not null && typeof(AIContent).IsAssignableFrom(baseType);
+             baseType = baseType.BaseType)
         {
-            if (typeInfo.Type == baseType)
+            AddDerivedAIContentType(options, baseType, contentType, typeDiscriminatorId);
+        }
+
+        static void AddDerivedAIContentType(JsonSerializerOptions options, Type baseType, Type contentType, string typeDiscriminatorId)
+        {
+            IJsonTypeInfoResolver resolver = options.TypeInfoResolver ?? DefaultOptions.TypeInfoResolver!;
+            options.TypeInfoResolver = resolver.WithAddedModifier(typeInfo =>
             {
-                (typeInfo.PolymorphismOptions ??= new()).DerivedTypes.Add(new(contentType, typeDiscriminatorId));
-            }
-        });
+                if (typeInfo.Type == baseType)
+                {
+                    (typeInfo.PolymorphismOptions ??= new()).DerivedTypes.Add(new(contentType, typeDiscriminatorId));
+                }
+            });
+        }
     }
 
 #if NET

test/Libraries/Microsoft.Extensions.AI.Abstractions.Tests/Utilities/AIJsonUtilitiesTests.cs

@@ -1223,6 +1223,180 @@ public static void AddAIContentType_NullArguments_ThrowsArgumentNullException()
         Assert.Throws<ArgumentNullException>("contentType", () => options.AddAIContentType(null!, "discriminator"));
     }
 
+    [Theory]
+    [InlineData(true)]
+    [InlineData(false)]
+    public static void AddAIContentType_LeafContent_RegistersInChain(bool useGenericOverload)
+    {
+        JsonSerializerOptions options = new()
+        {
+            TypeInfoResolver = JsonTypeInfoResolver.Combine(AIJsonUtilities.DefaultOptions.TypeInfoResolver, JsonContext.Default),
+        };
+
+        if (useGenericOverload)
+        {
+            options.AddAIContentType<LeafContent>("leaf");
+        }
+        else
+        {
+            options.AddAIContentType(typeof(LeafContent), "leaf");
+        }
+
+        // Verify LeafContent is registered as a derived type of both DerivedAIContent and AIContent.
+        var derivedAIContentTypes = options.GetTypeInfo(typeof(DerivedAIContent)).PolymorphismOptions!.DerivedTypes;
+        var aiContentTypes = options.GetTypeInfo(typeof(AIContent)).PolymorphismOptions!.DerivedTypes;
+        Assert.Contains(derivedAIContentTypes, dt => dt.DerivedType == typeof(LeafContent));
+        Assert.Contains(aiContentTypes, dt => dt.DerivedType == typeof(LeafContent));
+
+        // Verify serialization/deserialization works when typed as DerivedAIContent.
+        DerivedAIContent dc = new LeafContent { DerivedValue = 1, LeafValue = 42 };
+        string json = JsonSerializer.Serialize(dc, options);
+        Assert.Contains("\"$type\":\"leaf\"", json);
+        Assert.Contains("\"DerivedValue\":1", json);
+        Assert.Contains("\"LeafValue\":42", json);
+
+        LeafContent deserializedDc = Assert.IsType<LeafContent>(JsonSerializer.Deserialize<DerivedAIContent>(json, options));
+        Assert.Equal(1, deserializedDc.DerivedValue);
+        Assert.Equal(42, deserializedDc.LeafValue);
+
+        // Verify serialization/deserialization works when typed as AIContent.
+        AIContent ac = new LeafContent { DerivedValue = 2, LeafValue = 99 };
+        string json2 = JsonSerializer.Serialize(ac, options);
+        Assert.Contains("\"$type\":\"leaf\"", json2);
+        Assert.Contains("\"DerivedValue\":2", json2);
+        Assert.Contains("\"LeafValue\":99", json2);
+
+        LeafContent deserializedAc = Assert.IsType<LeafContent>(JsonSerializer.Deserialize<AIContent>(json2, options));
+        Assert.Equal(2, deserializedAc.DerivedValue);
+        Assert.Equal(99, deserializedAc.LeafValue);
+    }
+
+    [Theory]
+    [InlineData(true)]
+    [InlineData(false)]
+    public static void AddAIContentType_ChainWalksThroughBuiltInBaseTypes(bool useGenericOverload)
+    {
+        // Verifies that the chain registration walks through built-in intermediate types.
+        // For DerivedToolCallContent : ToolCallContent : AIContent, a single call should
+        // register against both ToolCallContent (built-in) and AIContent (built-in), so that
+        // deserialization works regardless of which base type the variable is declared as.
+        JsonSerializerOptions options = new()
+        {
+            TypeInfoResolver = JsonTypeInfoResolver.Combine(AIJsonUtilities.DefaultOptions.TypeInfoResolver, JsonContext.Default),
+        };
+
+        if (useGenericOverload)
+        {
+            options.AddAIContentType<DerivedToolCallContent>("derivedToolCall");
+        }
+        else
+        {
+            options.AddAIContentType(typeof(DerivedToolCallContent), "derivedToolCall");
+        }
+
+        // Verify DerivedToolCallContent is registered as a derived type of both ToolCallContent and AIContent.
+        var toolCallTypes = options.GetTypeInfo(typeof(ToolCallContent)).PolymorphismOptions!.DerivedTypes;
+        var aiContentTypes = options.GetTypeInfo(typeof(AIContent)).PolymorphismOptions!.DerivedTypes;
+        Assert.Contains(toolCallTypes, dt => dt.DerivedType == typeof(DerivedToolCallContent));
+        Assert.Contains(aiContentTypes, dt => dt.DerivedType == typeof(DerivedToolCallContent));
+
+        // Verify roundtrip when typed as ToolCallContent (built-in intermediate base).
+        ToolCallContent tc = new DerivedToolCallContent { CustomValue = 42 };
+        string json = JsonSerializer.Serialize(tc, options);
+        Assert.Contains("\"$type\":\"derivedToolCall\"", json);
+        Assert.Contains("\"CustomValue\":42", json);
+
+        DerivedToolCallContent deserializedTc = Assert.IsType<DerivedToolCallContent>(JsonSerializer.Deserialize<ToolCallContent>(json, options));
+        Assert.Equal(42, deserializedTc.CustomValue);
+
+        // Verify roundtrip when typed as AIContent (root base).
+        AIContent ac = new DerivedToolCallContent { CustomValue = 99 };
+        string json2 = JsonSerializer.Serialize(ac, options);
+        Assert.Contains("\"$type\":\"derivedToolCall\"", json2);
+        Assert.Contains("\"CustomValue\":99", json2);
+
+        DerivedToolCallContent deserializedAc = Assert.IsType<DerivedToolCallContent>(JsonSerializer.Deserialize<AIContent>(json2, options));
+        Assert.Equal(99, deserializedAc.CustomValue);
+    }
+
+    [Fact]
+    public static void AddAIContentType_OverlappingChains_RegistersBothCorrectly()
+    {
+        // Registers DerivedAIContent and LeafContent (which derives from DerivedAIContent).
+        // Both types should coexist: DerivedAIContent is registered under AIContent,
+        // and LeafContent is registered under both DerivedAIContent and AIContent.
+        JsonSerializerOptions options = new()
+        {
+            TypeInfoResolver = JsonTypeInfoResolver.Combine(AIJsonUtilities.DefaultOptions.TypeInfoResolver, JsonContext.Default),
+        };
+
+        options.AddAIContentType<DerivedAIContent>("derived");
+        options.AddAIContentType<LeafContent>("leaf");
+
+        // Verify registrations: AIContent should have both derived and leaf; DerivedAIContent should have leaf.
+        var aiContentDerivedTypes = options.GetTypeInfo(typeof(AIContent)).PolymorphismOptions!.DerivedTypes;
+        var derivedAIContentTypes = options.GetTypeInfo(typeof(DerivedAIContent)).PolymorphismOptions!.DerivedTypes;
+        Assert.Contains(aiContentDerivedTypes, dt => dt.DerivedType == typeof(DerivedAIContent));
+        Assert.Contains(aiContentDerivedTypes, dt => dt.DerivedType == typeof(LeafContent));
+        Assert.Contains(derivedAIContentTypes, dt => dt.DerivedType == typeof(LeafContent));
+
+        // DerivedAIContent roundtrips when typed as AIContent.
+        AIContent ac = new DerivedAIContent { DerivedValue = 1 };
+        string json = JsonSerializer.Serialize(ac, options);
+        Assert.Contains("\"$type\":\"derived\"", json);
+        DerivedAIContent deserializedDc = Assert.IsType<DerivedAIContent>(JsonSerializer.Deserialize<AIContent>(json, options));
+        Assert.Equal(1, deserializedDc.DerivedValue);
+
+        // LeafContent roundtrips when typed as DerivedAIContent.
+        DerivedAIContent dc = new LeafContent { DerivedValue = 2, LeafValue = 42 };
+        string json2 = JsonSerializer.Serialize(dc, options);
+        Assert.Contains("\"$type\":\"leaf\"", json2);
+        LeafContent deserializedLeaf = Assert.IsType<LeafContent>(JsonSerializer.Deserialize<DerivedAIContent>(json2, options));
+        Assert.Equal(2, deserializedLeaf.DerivedValue);
+        Assert.Equal(42, deserializedLeaf.LeafValue);
+
+        // LeafContent roundtrips when typed as AIContent.
+        AIContent ac2 = new LeafContent { DerivedValue = 3, LeafValue = 99 };
+        string json3 = JsonSerializer.Serialize(ac2, options);
+        Assert.Contains("\"$type\":\"leaf\"", json3);
+        LeafContent deserializedAc = Assert.IsType<LeafContent>(JsonSerializer.Deserialize<AIContent>(json3, options));
+        Assert.Equal(3, deserializedAc.DerivedValue);
+        Assert.Equal(99, deserializedAc.LeafValue);
+    }
+
+    [Fact]
+    public static void AddAIContentType_DoesNotRegisterIntermediateTypes()
+    {
+        // Registering LeafContent should NOT automatically register DerivedAIContent.
+        // Only the explicitly provided type gets a discriminator. This is by design:
+        // auto-registering intermediates would make it impossible to register multiple
+        // leaf types sharing a common base (the intermediate would be registered twice
+        // with no discriminator, or a conflicting one).
+        JsonSerializerOptions options = new()
+        {
+            TypeInfoResolver = JsonTypeInfoResolver.Combine(AIJsonUtilities.DefaultOptions.TypeInfoResolver, JsonContext.Default),
+        };
+
+        options.AddAIContentType<LeafContent>("leaf");
+
+        // Verify LeafContent is registered under both bases, but DerivedAIContent is NOT.
+        var aiContentDerivedTypes = options.GetTypeInfo(typeof(AIContent)).PolymorphismOptions!.DerivedTypes;
+        var derivedAIContentTypes = options.GetTypeInfo(typeof(DerivedAIContent)).PolymorphismOptions!.DerivedTypes;
+        Assert.Contains(aiContentDerivedTypes, dt => dt.DerivedType == typeof(LeafContent));
+        Assert.DoesNotContain(aiContentDerivedTypes, dt => dt.DerivedType == typeof(DerivedAIContent));
+        Assert.Contains(derivedAIContentTypes, dt => dt.DerivedType == typeof(LeafContent));
+
+        // LeafContent roundtrips fine when typed as AIContent.
+        AIContent ac = new LeafContent { DerivedValue = 1, LeafValue = 42 };
+        string json = JsonSerializer.Serialize(ac, options);
+        Assert.Contains("\"$type\":\"leaf\"", json);
+        Assert.IsType<LeafContent>(JsonSerializer.Deserialize<AIContent>(json, options));
+
+        // But a plain DerivedAIContent instance is NOT known to AIContent — no discriminator was registered for it.
+        AIContent unregistered = new DerivedAIContent { DerivedValue = 99 };
+        Assert.Throws<NotSupportedException>(() => JsonSerializer.Serialize(unregistered, options));
+    }
+
     [Fact]
     public static void HashData_Idempotent()
     {
@@ -1668,14 +1842,31 @@ public static void TransformJsonSchema_BooleanSchemas_Success(string booleanSche
         }
     }
 
+    private class LeafContent : DerivedAIContent
+    {
+        public int LeafValue { get; set; }
+    }
+
     private class DerivedAIContent : AIContent
     {
         public int DerivedValue { get; set; }
     }
 
+    private class DerivedToolCallContent : ToolCallContent
+    {
+        public DerivedToolCallContent()
+            : base("callId")
+        {
+        }
+
+        public int CustomValue { get; set; }
+    }
+
     [JsonSerializable(typeof(JsonElement))]
     [JsonSerializable(typeof(CreateJsonSchema_IncorporatesTypesAndAnnotations_Type))]
     [JsonSerializable(typeof(DerivedAIContent))]
+    [JsonSerializable(typeof(DerivedToolCallContent))]
+    [JsonSerializable(typeof(LeafContent))]
     [JsonSerializable(typeof(MyPoco))]
     [JsonSerializable(typeof(MyEnumValue?))]
     [JsonSerializable(typeof(object[]))]