.Net Improve type safety: Return TRecord instead of object in ITextSearch.GetSearchResultsAsync (#13318)

This PR enhances the type safety of the `ITextSearch<TRecord>` interface
by changing the `GetSearchResultsAsync` method to return
`KernelSearchResults<TRecord>` instead of `KernelSearchResults<object>`.
This improvement eliminates the need for manual casting and provides
better IntelliSense support for consumers.

## Motivation and Context

The current implementation of
`ITextSearch<TRecord>.GetSearchResultsAsync` returns
`KernelSearchResults<object>`, which requires consumers to manually cast
results to the expected type. This reduces type safety and degrades the
developer experience by losing compile-time type checking and
IntelliSense support.

This change aligns the return type with the generic type parameter
`TRecord`, providing the expected strongly-typed results that users of a
generic interface would anticipate.

## Changes Made

### Interface (ITextSearch.cs)
- Changed `ITextSearch<TRecord>.GetSearchResultsAsync` return type from
`KernelSearchResults<object>` to `KernelSearchResults<TRecord>`
- Updated XML documentation to reflect strongly-typed return value
- Legacy `ITextSearch` interface (non-generic) remains unchanged,
continuing to return `KernelSearchResults<object>` for backward
compatibility

### Implementation (VectorStoreTextSearch.cs)
- Added new `GetResultsAsTRecordAsync` helper method returning
`IAsyncEnumerable<TRecord>`
- Updated generic interface implementation to use the new strongly-typed
helper
- Retained `GetResultsAsRecordAsync` method for the legacy non-generic
interface

### Tests (VectorStoreTextSearchTests.cs)
- Updated 3 unit tests to use strongly-typed `DataModel` or
`DataModelWithRawEmbedding` instead of `object`
- Improved test assertions to leverage direct property access without
casting
- All 19 tests pass successfully

## Breaking Changes

**Interface Change (Experimental API):**
- `ITextSearch<TRecord>.GetSearchResultsAsync` now returns
`KernelSearchResults<TRecord>` instead of `KernelSearchResults<object>`
- This interface is marked with `[Experimental("SKEXP0001")]`,
indicating that breaking changes are expected during the preview period
- Legacy `ITextSearch` interface (non-generic) is unaffected and
maintains full backward compatibility

## Benefits

- **Improved Type Safety**: Eliminates runtime casting errors by
providing compile-time type checking
- **Enhanced Developer Experience**: Full IntelliSense support for
TRecord properties and methods
- **Cleaner Code**: Consumers no longer need to cast results from object
to the expected type
- **Consistent API Design**: Generic interface now behaves as expected,
returning strongly-typed results
- **Zero Impact on Legacy Code**: Non-generic ITextSearch interface
remains unchanged

## Testing

- All 19 existing unit tests pass
- Updated tests demonstrate improved type safety with direct property
access
- Verified both generic and legacy interfaces work correctly
- Confirmed zero breaking changes to non-generic ITextSearch consumers

## Related Work

This PR is part of the Issue #10456 multi-PR chain for modernizing
ITextSearch with LINQ-based filtering:
- PR #13175: Foundation (ITextSearch<TRecord> interface) - Merged
- PR #13179: VectorStoreTextSearch + deprecation pattern - In Review
- **This PR (2.1)**: API refinement for improved type safety
- PR #13188-13191: Connector migrations (Bing, Google, Tavily, Brave) -
Pending
- PR #13194: Samples and documentation - Pending

All PRs target the `feature-text-search-linq` branch for coordinated
release.

## Migration Guide for Consumers

### Before (Previous API)
```csharp
ITextSearch<DataModel> search = ...;
KernelSearchResults<object> results = await search.GetSearchResultsAsync("query", options);

foreach (var obj in results.Results)
{
    var record = (DataModel)obj;  // Manual cast required
    Console.WriteLine(record.Name);
}
```

### After (Improved API)
```csharp
ITextSearch<DataModel> search = ...;
KernelSearchResults<DataModel> results = await search.GetSearchResultsAsync("query", options);

foreach (var record in results.Results)  // Strongly typed!
{
    Console.WriteLine(record.Name);  // Direct property access with IntelliSense
}
```

## Checklist

- [x] Changes build successfully
- [x] All unit tests pass (19/19)
- [x] XML documentation updated
- [x] Breaking change documented (experimental API only)
- [x] Legacy interface backward compatibility maintained
- [x] Code follows project coding standards

Co-authored-by: Alexander Zarei <alzarei@users.noreply.github.com>

Author: alzarei

dotnet/src/SemanticKernel.Abstractions/Data/TextSearch/ITextSearch.cs

@@ -36,12 +36,12 @@ Task<KernelSearchResults<TextSearchResult>> GetTextSearchResultsAsync(
         CancellationToken cancellationToken = default);
 
     /// <summary>
-    /// Perform a search for content related to the specified query and return <see cref="object"/> values representing the search results.
+    /// Perform a search for content related to the specified query and return strongly-typed <typeparamref name="TRecord"/> values representing the search results.
     /// </summary>
     /// <param name="query">What to search for.</param>
     /// <param name="searchOptions">Options used when executing a text search.</param>
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
-    Task<KernelSearchResults<object>> GetSearchResultsAsync(
+    Task<KernelSearchResults<TRecord>> GetSearchResultsAsync(
         string query,
         TextSearchOptions<TRecord>? searchOptions = null,
         CancellationToken cancellationToken = default);

dotnet/src/SemanticKernel.Core/Data/TextSearch/VectorStoreTextSearch.cs

@@ -213,11 +213,11 @@ Task<KernelSearchResults<TextSearchResult>> ITextSearch<TRecord>.GetTextSearchRe
     }
 
     /// <inheritdoc/>
-    Task<KernelSearchResults<object>> ITextSearch<TRecord>.GetSearchResultsAsync(string query, TextSearchOptions<TRecord>? searchOptions, CancellationToken cancellationToken)
+    Task<KernelSearchResults<TRecord>> ITextSearch<TRecord>.GetSearchResultsAsync(string query, TextSearchOptions<TRecord>? searchOptions, CancellationToken cancellationToken)
     {
         var searchResponse = this.ExecuteVectorSearchAsync(query, searchOptions, cancellationToken);
 
-        return Task.FromResult(new KernelSearchResults<object>(this.GetResultsAsRecordAsync(searchResponse, cancellationToken)));
+        return Task.FromResult(new KernelSearchResults<TRecord>(this.GetResultsAsTRecordAsync(searchResponse, cancellationToken)));
     }
 
     #region private
@@ -367,6 +367,28 @@ private async IAsyncEnumerable<object> GetResultsAsRecordAsync(IAsyncEnumerable<
         }
     }
 
+    /// <summary>
+    /// Return the search results as strongly-typed <typeparamref name="TRecord"/> instances.
+    /// </summary>
+    /// <param name="searchResponse">Response containing the records matching the query.</param>
+    /// <param name="cancellationToken">Cancellation token</param>
+    private async IAsyncEnumerable<TRecord> GetResultsAsTRecordAsync(IAsyncEnumerable<VectorSearchResult<TRecord>>? searchResponse, [EnumeratorCancellation] CancellationToken cancellationToken)
+    {
+        if (searchResponse is null)
+        {
+            yield break;
+        }
+
+        await foreach (var result in searchResponse.WithCancellation(cancellationToken).ConfigureAwait(false))
+        {
+            if (result.Record is not null)
+            {
+                yield return result.Record;
+                await Task.Yield();
+            }
+        }
+    }
+
     /// <summary>
     /// Return the search results as instances of <see cref="TextSearchResult"/>.
     /// </summary>

dotnet/src/SemanticKernel.UnitTests/Data/VectorStoreTextSearchTests.cs

@@ -78,12 +78,14 @@ public async Task CanGetSearchResultAsync()
     {
         // Arrange.
         var sut = await CreateVectorStoreTextSearchAsync();
+        ITextSearch<DataModel> typeSafeInterface = sut;
 
         // Act.
-        KernelSearchResults<object> searchResults = await sut.GetSearchResultsAsync("What is the Semantic Kernel?", new() { Top = 2, Skip = 0 });
+        KernelSearchResults<DataModel> searchResults = await typeSafeInterface.GetSearchResultsAsync("What is the Semantic Kernel?", new TextSearchOptions<DataModel> { Top = 2, Skip = 0 });
         var results = await searchResults.Results.ToListAsync();
 
         Assert.Equal(2, results.Count);
+        Assert.All(results, result => Assert.IsType<DataModel>(result));
     }
 
     [Fact]
@@ -117,12 +119,14 @@ public async Task CanGetSearchResultsWithEmbeddingGeneratorAsync()
     {
         // Arrange.
         var sut = await CreateVectorStoreTextSearchWithEmbeddingGeneratorAsync();
+        ITextSearch<DataModelWithRawEmbedding> typeSafeInterface = sut;
 
         // Act.
-        KernelSearchResults<object> searchResults = await sut.GetSearchResultsAsync("What is the Semantic Kernel?", new() { Top = 2, Skip = 0 });
+        KernelSearchResults<DataModelWithRawEmbedding> searchResults = await typeSafeInterface.GetSearchResultsAsync("What is the Semantic Kernel?", new TextSearchOptions<DataModelWithRawEmbedding> { Top = 2, Skip = 0 });
         var results = await searchResults.Results.ToListAsync();
 
         Assert.Equal(2, results.Count);
+        Assert.All(results, result => Assert.IsType<DataModelWithRawEmbedding>(result));
     }
 
 #pragma warning disable CS0618 // VectorStoreTextSearch with ITextEmbeddingGenerationService is obsolete
@@ -270,17 +274,16 @@ public async Task LinqGetSearchResultsAsync()
             Filter = r => r.Tag == "Even"
         };
 
-        KernelSearchResults<object> searchResults = await typeSafeInterface.GetSearchResultsAsync(
+        KernelSearchResults<DataModel> searchResults = await typeSafeInterface.GetSearchResultsAsync(
             "What is the Semantic Kernel?",
             searchOptions);
         var results = await searchResults.Results.ToListAsync();
 
-        // Assert - Results should be DataModel objects with Tag == "Even"
+        // Assert - Results should be strongly-typed DataModel objects with Tag == "Even"
         Assert.NotEmpty(results);
         Assert.All(results, result =>
         {
-            var dataModel = Assert.IsType<DataModel>(result);
-            Assert.Equal("Even", dataModel.Tag);
+            Assert.Equal("Even", result.Tag); // Direct property access - no cast needed!
         });
     }