[release/9.0] Merging changes from main into release branch for November release (#5602)

Author: joperezr

Diff for: eng/MSBuild/LegacySupport.props

@@ -43,6 +43,10 @@
     <Compile Include="$(MSBuildThisFileDirectory)\..\..\src\LegacySupport\StringSyntaxAttribute\*.cs" LinkBase="LegacySupport\StringSyntaxAttribute" />
   </ItemGroup>
 
+  <ItemGroup Condition="'$(InjectJsonSchemaExporterOnLegacy)' == 'true' AND ('$(TargetFramework)' == 'net462' or '$(TargetFramework)' == 'netstandard2.0' or '$(TargetFramework)' == 'netcoreapp3.1' or '$(TargetFramework)' == 'net6.0' or '$(TargetFramework)' == 'net7.0' or '$(TargetFramework)' == 'net8.0')">
+    <Compile Include="$(MSBuildThisFileDirectory)\..\..\src\Shared\JsonSchemaExporter\**\*.cs" LinkBase="Shared\EmptyCollections" />
+  </ItemGroup>
+
   <ItemGroup Condition="'$(InjectGetOrAddOnLegacy)' == 'true' AND ('$(TargetFramework)' == 'net462' or '$(TargetFramework)' == 'netstandard2.0')">
     <Compile Include="$(MSBuildThisFileDirectory)\..\..\src\LegacySupport\GetOrAdd\*.cs" LinkBase="LegacySupport\GetOrAdd" />
   </ItemGroup>

Diff for: eng/packages/TestOnly.props

@@ -7,6 +7,7 @@
     <PackageVersion Include="BenchmarkDotNet" Version="0.13.5" />
     <PackageVersion Include="FluentAssertions" Version="6.11.0" />
     <PackageVersion Include="Grpc.AspNetCore" Version="2.65.0" />
+    <PackageVersion Include="JsonSchema.Net" Version="7.2.3" />
     <PackageVersion Include="Microsoft.Data.SqlClient" Version="5.2.2" />
     <PackageVersion Include="Microsoft.Diagnostics.Tracing.TraceEvent" Version="3.1.3" />
     <PackageVersion Include="Microsoft.ML.Tokenizers" Version="0.22.0-preview.24378.1" />
@@ -20,6 +21,7 @@
     <PackageVersion Include="Verify.Xunit" Version="20.4.0" />
     <PackageVersion Include="Xunit.Combinatorial" Version="1.6.24" />
     <PackageVersion Include="xunit.extensibility.execution" Version="2.4.2" />
+    <PackageVersion Include="Xunit.SkippableFact" Version="1.4.13" />
   </ItemGroup>
 
   <ItemGroup Condition="'$(TargetFramework)' == 'net462'">

Diff for: eng/spellchecking_exclusions.dic

@@ -4,13 +4,21 @@
 using System;
 using System.Collections;
 using System.Collections.Generic;
+using System.Diagnostics;
 using System.Diagnostics.CodeAnalysis;
 using System.Globalization;
 using System.Linq;
+using Microsoft.Shared.Diagnostics;
+
+#pragma warning disable S1144 // Unused private types or members should be removed
+#pragma warning disable S2365 // Properties should not make collection or array copies
+#pragma warning disable S3604 // Member initializer values should not be redundant
 
 namespace Microsoft.Extensions.AI;
 
 /// <summary>Provides a dictionary used as the AdditionalProperties dictionary on Microsoft.Extensions.AI objects.</summary>
+[DebuggerTypeProxy(typeof(DebugView))]
+[DebuggerDisplay("Count = {Count}")]
 public sealed class AdditionalPropertiesDictionary : IDictionary<string, object?>, IReadOnlyDictionary<string, object?>
 {
     /// <summary>The underlying dictionary.</summary>
@@ -77,6 +85,25 @@ public object? this[string key]
     /// <inheritdoc />
     public void Add(string key, object? value) => _dictionary.Add(key, value);
 
+    /// <summary>Attempts to add the specified key and value to the dictionary.</summary>
+    /// <param name="key">The key of the element to add.</param>
+    /// <param name="value">The value of the element to add.</param>
+    /// <returns><see langword="true"/> if the key/value pair was added to the dictionary successfully; otherwise, <see langword="false"/>.</returns>
+    public bool TryAdd(string key, object? value)
+    {
+#if NET
+        return _dictionary.TryAdd(key, value);
+#else
+        if (!_dictionary.ContainsKey(key))
+        {
+            _dictionary.Add(key, value);
+            return true;
+        }
+
+        return false;
+#endif
+    }
+
     /// <inheritdoc />
     void ICollection<KeyValuePair<string, object?>>.Add(KeyValuePair<string, object?> item) => ((ICollection<KeyValuePair<string, object?>>)_dictionary).Add(item);
 
@@ -93,11 +120,17 @@ public object? this[string key]
     void ICollection<KeyValuePair<string, object?>>.CopyTo(KeyValuePair<string, object?>[] array, int arrayIndex) =>
         ((ICollection<KeyValuePair<string, object?>>)_dictionary).CopyTo(array, arrayIndex);
 
+    /// <summary>
+    /// Returns an enumerator that iterates through the <see cref="AdditionalPropertiesDictionary"/>.
+    /// </summary>
+    /// <returns>An <see cref="AdditionalPropertiesDictionary.Enumerator"/> that enumerates the contents of the <see cref="AdditionalPropertiesDictionary"/>.</returns>
+    public Enumerator GetEnumerator() => new(_dictionary.GetEnumerator());
+
     /// <inheritdoc />
-    public IEnumerator<KeyValuePair<string, object?>> GetEnumerator() => _dictionary.GetEnumerator();
+    IEnumerator<KeyValuePair<string, object?>> IEnumerable<KeyValuePair<string, object?>>.GetEnumerator() => GetEnumerator();
 
     /// <inheritdoc />
-    IEnumerator IEnumerable.GetEnumerator() => _dictionary.GetEnumerator();
+    IEnumerator IEnumerable.GetEnumerator() => GetEnumerator();
 
     /// <inheritdoc />
     public bool Remove(string key) => _dictionary.Remove(key);
@@ -156,4 +189,59 @@ public bool TryGetValue<T>(string key, [NotNullWhen(true)] out T? value)
         value = default;
         return false;
     }
+
+    /// <summary>Enumerates the elements of an <see cref="AdditionalPropertiesDictionary"/>.</summary>
+    public struct Enumerator : IEnumerator<KeyValuePair<string, object?>>
+    {
+        /// <summary>The wrapped dictionary enumerator.</summary>
+        private Dictionary<string, object?>.Enumerator _dictionaryEnumerator;
+
+        /// <summary>Initializes a new instance of the <see cref="Enumerator"/> struct with the dictionary enumerator to wrap.</summary>
+        /// <param name="dictionaryEnumerator">The dictionary enumerator to wrap.</param>
+        internal Enumerator(Dictionary<string, object?>.Enumerator dictionaryEnumerator)
+        {
+            _dictionaryEnumerator = dictionaryEnumerator;
+        }
+
+        /// <inheritdoc />
+        public KeyValuePair<string, object?> Current => _dictionaryEnumerator.Current;
+
+        /// <inheritdoc />
+        object IEnumerator.Current => Current;
+
+        /// <inheritdoc />
+        public void Dispose() => _dictionaryEnumerator.Dispose();
+
+        /// <inheritdoc />
+        public bool MoveNext() => _dictionaryEnumerator.MoveNext();
+
+        /// <inheritdoc />
+        public void Reset() => Reset(ref _dictionaryEnumerator);
+
+        /// <summary>Calls <see cref="IEnumerator.Reset"/> on an enumerator.</summary>
+        private static void Reset<TEnumerator>(ref TEnumerator enumerator)
+            where TEnumerator : struct, IEnumerator
+        {
+            enumerator.Reset();
+        }
+    }
+
+    /// <summary>Provides a debugger view for the collection.</summary>
+    private sealed class DebugView(AdditionalPropertiesDictionary properties)
+    {
+        private readonly AdditionalPropertiesDictionary _properties = Throw.IfNull(properties);
+
+        [DebuggerBrowsable(DebuggerBrowsableState.RootHidden)]
+        public AdditionalProperty[] Items => (from p in _properties select new AdditionalProperty(p.Key, p.Value)).ToArray();
+
+        [DebuggerDisplay("{Value}", Name = "[{Key}]")]
+        public readonly struct AdditionalProperty(string key, object? value)
+        {
+            [DebuggerBrowsable(DebuggerBrowsableState.Collapsed)]
+            public string Key { get; } = key;
+
+            [DebuggerBrowsable(DebuggerBrowsableState.Collapsed)]
+            public object? Value { get; } = value;
+        }
+    }
 }

Diff for: src/Libraries/Microsoft.Extensions.AI.Abstractions/AdditionalPropertiesDictionary.cs

@@ -0,0 +1,19 @@
+# Release History
+
+## 9.0.0-preview.9.24525.1
+
+- Lowered the required version of System.Text.Json to 8.0.5 when targeting net8.0 or older.
+- Annotated `FunctionCallContent.Exception` and `FunctionResultContent.Exception` as `[JsonIgnore]`, such that they're ignored when serializing instances with `JsonSerializer`. The corresponding constructors accepting an `Exception` were removed.
+- Annotated `ChatCompletion.Message` as `[JsonIgnore]`, such that it's ignored when serializing instances with `JsonSerializer`.
+- Added the `FunctionCallContent.CreateFromParsedArguments` method.
+- Added the `AdditionalPropertiesDictionary.TryGetValue<T>` method.
+- Added the `StreamingChatCompletionUpdate.ModelId` property and removed the `AIContent.ModelId` property.
+- Renamed the `GenerateAsync` extension method on `IEmbeddingGenerator<,>` to `GenerateEmbeddingsAsync` and updated it to return `Embedding<T>` rather than `GeneratedEmbeddings`.
+- Added `GenerateAndZipAsync` and `GenerateEmbeddingVectorAsync` extension methods for `IEmbeddingGenerator<,>`.
+- Added the `EmbeddingGeneratorOptions.Dimensions` property.
+- Added the `ChatOptions.TopK` property.
+- Normalized `null` inputs in `TextContent` to be empty strings.
+
+## 9.0.0-preview.9.24507.7
+
+Initial Preview

Diff for: src/Libraries/Microsoft.Extensions.AI.Abstractions/CHANGELOG.md

@@ -27,6 +27,9 @@ public class ChatOptions
     /// <summary>Gets or sets the presence penalty for generating chat responses.</summary>
     public float? PresencePenalty { get; set; }
 
+    /// <summary>Gets or sets a seed value used by a service to control the reproducability of results.</summary>
+    public long? Seed { get; set; }
+
     /// <summary>
     /// Gets or sets the response format for the chat request.
     /// </summary>
@@ -74,6 +77,7 @@ public virtual ChatOptions Clone()
             TopK = TopK,
             FrequencyPenalty = FrequencyPenalty,
             PresencePenalty = PresencePenalty,
+            Seed = Seed,
             ResponseFormat = ResponseFormat,
             ModelId = ModelId,
             ToolMode = ToolMode,

Diff for: src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatOptions.cs

@@ -16,9 +16,11 @@
     <TargetFrameworks>$(TargetFrameworks);netstandard2.0</TargetFrameworks>
     <NoWarn>$(NoWarn);CA2227;CA1034;SA1316;S3253</NoWarn>
     <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+    <DisableNETStandardCompatErrors>true</DisableNETStandardCompatErrors>
   </PropertyGroup>
 
   <PropertyGroup>
+    <InjectJsonSchemaExporterOnLegacy>true</InjectJsonSchemaExporterOnLegacy>
     <InjectSharedEmptyCollections>true</InjectSharedEmptyCollections>
     <InjectStringHashOnLegacy>true</InjectStringHashOnLegacy>
     <InjectStringSyntaxAttributeOnLegacy>true</InjectStringSyntaxAttributeOnLegacy>

Diff for: src/Libraries/Microsoft.Extensions.AI.Abstractions/Microsoft.Extensions.AI.Abstractions.csproj

@@ -23,11 +23,11 @@ private static JsonSerializerOptions CreateDefaultOptions()
     {
         // If reflection-based serialization is enabled by default, use it, as it's the most permissive in terms of what it can serialize,
         // and we want to be flexible in terms of what can be put into the various collections in the object model.
-        // Otherwise, use the source-generated options to enable Native AOT.
+        // Otherwise, use the source-generated options to enable trimming and Native AOT.
 
         if (JsonSerializer.IsReflectionEnabledByDefault)
         {
-            // Keep in sync with the JsonSourceGenerationOptions on JsonContext below.
+            // Keep in sync with the JsonSourceGenerationOptions attribute on JsonContext below.
             JsonSerializerOptions options = new(JsonSerializerDefaults.Web)
             {
                 TypeInfoResolver = new DefaultJsonTypeInfoResolver(),