.NET: Add ITextSearch<TRecord> with LINQ filtering and deprecate legacy ITextSearch (#10456)

dotnet/samples/GettingStartedWithTextSearch/Step1_Web_Search.cs

@@ -1,5 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+#pragma warning disable CS0618 // ITextSearch is obsolete - Sample demonstrates legacy interface usage
+
 using Microsoft.SemanticKernel.Data;
 using Microsoft.SemanticKernel.Plugins.Web.Bing;
 using Microsoft.SemanticKernel.Plugins.Web.Google;

dotnet/samples/GettingStartedWithTextSearch/Step2_Search_For_RAG.cs

@@ -1,4 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.
+
+#pragma warning disable CS0618 // ITextSearch is obsolete - Sample demonstrates legacy interface usage
+
 using System.Text.RegularExpressions;
 using HtmlAgilityPack;
 using Microsoft.SemanticKernel;

dotnet/src/IntegrationTests/Agents/CommonInterfaceConformance/AgentWithTextSearchProviderConformance/AgentWithTextSearchProvider.cs

@@ -41,7 +41,9 @@ public abstract class AgentWithTextSearchProvider<TFixture>(Func<TFixture> creat
     public async Task TextSearchBehaviorStateIsUsedByAgentInternalAsync(string question, string expectedResult, params string[] ragResults)
     {
         // Arrange
+#pragma warning disable CS0618 // ITextSearch is obsolete - Testing legacy interface
         var mockTextSearch = new Mock<ITextSearch>();
+#pragma warning restore CS0618
         mockTextSearch.Setup(x => x.GetTextSearchResultsAsync(
             It.IsAny<string>(),
             It.IsAny<TextSearchOptions>(),

dotnet/src/IntegrationTests/Connectors/Memory/AzureAISearch/AzureAISearchTextSearchTests.cs

@@ -1,5 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+#pragma warning disable CS0618 // ITextSearch is obsolete
+
 using System;
 using System.Threading.Tasks;
 using Azure.AI.OpenAI;

dotnet/src/IntegrationTests/Connectors/Memory/InMemory/InMemoryVectorStoreTextSearchTests.cs

@@ -1,5 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+#pragma warning disable CS0618 // ITextSearch is obsolete
+
 using System;
 using System.Threading.Tasks;
 using Microsoft.Extensions.AI;

dotnet/src/IntegrationTests/Connectors/Memory/Qdrant/QdrantTextSearchTests.cs

@@ -1,5 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+#pragma warning disable CS0618 // ITextSearch is obsolete
+
 using System;
 using System.Threading.Tasks;
 using Microsoft.SemanticKernel.Connectors.Qdrant;

dotnet/src/IntegrationTests/Data/BaseTextSearchTests.cs

@@ -1,5 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+#pragma warning disable CS0618 // Type or member is obsolete - Testing legacy non-generic ITextSearch interface
+
 using System;
 using System.Collections.Generic;
 using System.Linq;

dotnet/src/IntegrationTests/Plugins/Web/Bing/BingTextSearchTests.cs

@@ -1,5 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+#pragma warning disable CS0618 // ITextSearch is obsolete
+
 using System.Threading.Tasks;
 using Microsoft.Extensions.Configuration;
 using Microsoft.SemanticKernel.Data;

dotnet/src/IntegrationTests/Plugins/Web/Google/GoogleTextSearchTests.cs

@@ -1,5 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+#pragma warning disable CS0618 // ITextSearch is obsolete
+
 using System.Threading.Tasks;
 using Microsoft.Extensions.Configuration;
 using Microsoft.SemanticKernel.Data;

dotnet/src/IntegrationTests/Plugins/Web/Tavily/TavilyTextSearchTests.cs

@@ -1,5 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+#pragma warning disable CS0618 // ITextSearch is obsolete
+
 using System.Threading.Tasks;
 using Microsoft.Extensions.Configuration;
 using Microsoft.SemanticKernel.Data;

dotnet/src/Plugins/Plugins.UnitTests/Web/Bing/BingTextSearchTests.cs

@@ -1,5 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+#pragma warning disable CS0618 // ITextSearch is obsolete
+
 using System;
 using System.IO;
 using System.Linq;

dotnet/src/Plugins/Plugins.UnitTests/Web/Brave/BraveTextSearchTests.cs

@@ -1,5 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+#pragma warning disable CS0618 // ITextSearch is obsolete
+
 using System;
 using System.IO;
 using System.Linq;

dotnet/src/Plugins/Plugins.UnitTests/Web/Google/GoogleTextSearchTests.cs

@@ -1,5 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+#pragma warning disable CS0618 // ITextSearch is obsolete
+
 using System;
 using System.IO;
 using System.Linq;

dotnet/src/Plugins/Plugins.UnitTests/Web/Tavily/TavilyTextSearchTests.cs

@@ -1,5 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+#pragma warning disable CS0618 // ITextSearch is obsolete
+
 using System;
 using System.IO;
 using System.Linq;

dotnet/src/Plugins/Plugins.Web/Bing/BingTextSearch.cs

@@ -20,7 +20,9 @@ namespace Microsoft.SemanticKernel.Plugins.Web.Bing;
 /// <summary>
 /// A Bing Text Search implementation that can be used to perform searches using the Bing Web Search API.
 /// </summary>
+#pragma warning disable CS0618 // ITextSearch is obsolete - this class provides backward compatibility
 public sealed class BingTextSearch : ITextSearch
+#pragma warning restore CS0618
 {
     /// <summary>
     /// Create an instance of the <see cref="BingTextSearch"/> with API key authentication.

dotnet/src/Plugins/Plugins.Web/Brave/BraveTextSearch.cs

@@ -20,7 +20,9 @@ namespace Microsoft.SemanticKernel.Plugins.Web.Brave;
 /// <summary>
 /// A Brave Text Search implementation that can be used to perform searches using the Brave Web Search API.
 /// </summary>
+#pragma warning disable CS0618 // ITextSearch is obsolete - this class provides backward compatibility
 public sealed class BraveTextSearch : ITextSearch
+#pragma warning restore CS0618
 {
     /// <summary>
     /// Create an instance of the <see cref="BraveTextSearch"/> with API key authentication.

dotnet/src/Plugins/Plugins.Web/Google/GoogleTextSearch.cs

@@ -17,7 +17,9 @@ namespace Microsoft.SemanticKernel.Plugins.Web.Google;
 /// <summary>
 /// A Google Text Search implementation that can be used to perform searches using the Google Web Search API.
 /// </summary>
+#pragma warning disable CS0618 // ITextSearch is obsolete - this class provides backward compatibility
 public sealed class GoogleTextSearch : ITextSearch, IDisposable
+#pragma warning restore CS0618
 {
     /// <summary>
     /// Initializes a new instance of the <see cref="GoogleTextSearch"/> class.

dotnet/src/Plugins/Plugins.Web/Tavily/TavilyTextSearch.cs

@@ -20,7 +20,9 @@ namespace Microsoft.SemanticKernel.Plugins.Web.Tavily;
 /// <summary>
 /// A Tavily Text Search implementation that can be used to perform searches using the Tavily Web Search API.
 /// </summary>
+#pragma warning disable CS0618 // ITextSearch is obsolete - this class provides backward compatibility
 public sealed class TavilyTextSearch : ITextSearch
+#pragma warning restore CS0618
 {
     /// <summary>
     /// Create an instance of the <see cref="TavilyTextSearch"/> with API key authentication.

dotnet/src/Plugins/Plugins.Web/WebServiceCollectionExtensions.cs

@@ -1,5 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+#pragma warning disable CS0618 // ITextSearch is obsolete - these extension methods provide backward compatibility
+
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.SemanticKernel.Data;
 using Microsoft.SemanticKernel.Plugins.Web.Bing;

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

@@ -1,13 +1,12 @@
 // Copyright (c) Microsoft. All rights reserved.
 
 using System.Diagnostics.CodeAnalysis;
-using System.Threading;
-using System.Threading.Tasks;
 
 namespace Microsoft.SemanticKernel.Data;
 
 /// <summary>
 /// Interface for text based search queries with type-safe LINQ filtering for use with Semantic Kernel prompts and automatic function calling.
+/// This generic interface supports LINQ-based filtering through <see cref="TextSearchOptions{TRecord}"/> for type-safe queries.
 /// </summary>
 /// <typeparam name="TRecord">The type of record being searched.</typeparam>
 [Experimental("SKEXP0001")]
@@ -18,70 +17,72 @@ public interface ITextSearch<TRecord>
     /// </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<string>> SearchAsync(
+    /// <param name="cancellationToken">The <see cref="System.Threading.CancellationToken"/> to monitor for cancellation requests. The default is <see cref="System.Threading.CancellationToken.None"/>.</param>
+    System.Threading.Tasks.Task<KernelSearchResults<string>> SearchAsync(
         string query,
         TextSearchOptions<TRecord>? searchOptions = null,
-        CancellationToken cancellationToken = default);
+        System.Threading.CancellationToken cancellationToken = default);
 
     /// <summary>
     /// Perform a search for content related to the specified query and return <see cref="TextSearchResult"/> 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<TextSearchResult>> GetTextSearchResultsAsync(
+    /// <param name="cancellationToken">The <see cref="System.Threading.CancellationToken"/> to monitor for cancellation requests. The default is <see cref="System.Threading.CancellationToken.None"/>.</param>
+    System.Threading.Tasks.Task<KernelSearchResults<TextSearchResult>> GetTextSearchResultsAsync(
         string query,
         TextSearchOptions<TRecord>? searchOptions = null,
-        CancellationToken cancellationToken = default);
+        System.Threading.CancellationToken cancellationToken = default);
 
     /// <summary>
     /// Perform a search for content related to the specified query and return <see cref="object"/> 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(
+    /// <param name="cancellationToken">The <see cref="System.Threading.CancellationToken"/> to monitor for cancellation requests. The default is <see cref="System.Threading.CancellationToken.None"/>.</param>
+    System.Threading.Tasks.Task<KernelSearchResults<object>> GetSearchResultsAsync(
         string query,
         TextSearchOptions<TRecord>? searchOptions = null,
-        CancellationToken cancellationToken = default);
+        System.Threading.CancellationToken cancellationToken = default);
 }
 
 /// <summary>
 /// Interface for text based search queries for use with Semantic Kernel prompts and automatic function calling.
+/// This non-generic interface uses legacy <see cref="TextSearchFilter"/> for backward compatibility.
 /// </summary>
+[System.Obsolete("Use ITextSearch<TRecord> with LINQ-based filtering instead. This interface will be removed in a future version.")]
 public interface ITextSearch
 {
     /// <summary>
     /// Perform a search for content related to the specified query and return <see cref="string"/> 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<string>> SearchAsync(
+    /// <param name="cancellationToken">The <see cref="System.Threading.CancellationToken"/> to monitor for cancellation requests. The default is <see cref="System.Threading.CancellationToken.None"/>.</param>
+    System.Threading.Tasks.Task<KernelSearchResults<string>> SearchAsync(
         string query,
         TextSearchOptions? searchOptions = null,
-        CancellationToken cancellationToken = default);
+        System.Threading.CancellationToken cancellationToken = default);
 
     /// <summary>
     /// Perform a search for content related to the specified query and return <see cref="TextSearchResult"/> 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<TextSearchResult>> GetTextSearchResultsAsync(
+    /// <param name="cancellationToken">The <see cref="System.Threading.CancellationToken"/> to monitor for cancellation requests. The default is <see cref="System.Threading.CancellationToken.None"/>.</param>
+    System.Threading.Tasks.Task<KernelSearchResults<TextSearchResult>> GetTextSearchResultsAsync(
         string query,
         TextSearchOptions? searchOptions = null,
-        CancellationToken cancellationToken = default);
+        System.Threading.CancellationToken cancellationToken = default);
 
     /// <summary>
     /// Perform a search for content related to the specified query and return <see cref="object"/> 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(
+    /// <param name="cancellationToken">The <see cref="System.Threading.CancellationToken"/> to monitor for cancellation requests. The default is <see cref="System.Threading.CancellationToken.None"/>.</param>
+    System.Threading.Tasks.Task<KernelSearchResults<object>> GetSearchResultsAsync(
         string query,
         TextSearchOptions? searchOptions = null,
-        CancellationToken cancellationToken = default);
+        System.Threading.CancellationToken cancellationToken = default);
 }

dotnet/src/SemanticKernel.AotTests/UnitTests/Search/MockTextSearch.cs

@@ -4,7 +4,9 @@
 
 namespace SemanticKernel.AotTests.UnitTests.Search;
 
+#pragma warning disable CS0618 // Type or member is obsolete
 internal sealed class MockTextSearch : ITextSearch
+#pragma warning restore CS0618 // Type or member is obsolete
 {
     private readonly KernelSearchResults<object>? _objectResults;
     private readonly KernelSearchResults<TextSearchResult>? _textSearchResults;

dotnet/src/SemanticKernel.AotTests/UnitTests/Search/TextSearchExtensionsTests.cs

@@ -21,7 +21,9 @@ public static async Task CreateWithSearch()
         // Arrange
         var testData = new List<string> { "test-value" };
         KernelSearchResults<string> results = new(testData.ToAsyncEnumerable());
+#pragma warning disable CS0618 // Type or member is obsolete
         ITextSearch textSearch = new MockTextSearch(results);
+#pragma warning restore CS0618 // Type or member is obsolete
 
         // Act
         var plugin = textSearch.CreateWithSearch("SearchPlugin", s_jsonSerializerOptions);
@@ -35,7 +37,9 @@ public static async Task CreateWithGetTextSearchResults()
         // Arrange
         var testData = new List<TextSearchResult> { new("test-value") };
         KernelSearchResults<TextSearchResult> results = new(testData.ToAsyncEnumerable());
+#pragma warning disable CS0618 // Type or member is obsolete
         ITextSearch textSearch = new MockTextSearch(results);
+#pragma warning restore CS0618 // Type or member is obsolete
 
         // Act
         var plugin = textSearch.CreateWithGetTextSearchResults("SearchPlugin", s_jsonSerializerOptions);
@@ -49,7 +53,9 @@ public static async Task CreateWithGetSearchResults()
         // Arrange
         var testData = new List<CustomResult> { new("test-value") };
         KernelSearchResults<object> results = new(testData.ToAsyncEnumerable());
+#pragma warning disable CS0618 // Type or member is obsolete
         ITextSearch textSearch = new MockTextSearch(results);
+#pragma warning restore CS0618 // Type or member is obsolete
 
         // Act
         var plugin = textSearch.CreateWithGetSearchResults("SearchPlugin", s_jsonSerializerOptions);

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

@@ -1,5 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+#pragma warning disable CS0618 // ITextSearch is obsolete - these extension methods provide backward compatibility
+
 using System.Collections.Generic;
 using System.Diagnostics.CodeAnalysis;
 using System.Linq;

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

@@ -16,7 +16,9 @@ namespace Microsoft.SemanticKernel.Data;
 /// A Vector Store Text Search implementation that can be used to perform searches using a <see cref="VectorStoreCollection{TKey, TRecord}"/>.
 /// </summary>
 [Experimental("SKEXP0001")]
+#pragma warning disable CS0618 // ITextSearch is obsolete - this class provides backward compatibility
 public sealed class VectorStoreTextSearch<[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicProperties)] TRecord> : ITextSearch<TRecord>, ITextSearch
+#pragma warning restore CS0618
 #pragma warning restore CA1711 // Identifiers should not have incorrect suffix
 {
     /// <summary>
@@ -268,19 +270,22 @@ private TextSearchStringMapper CreateTextSearchStringMapper()
     }
 
     /// <summary>
-    /// Execute a vector search and return the results.
+    /// Execute a vector search and return the results using legacy filtering for backward compatibility.
     /// </summary>
     /// <param name="query">What to search for.</param>
-    /// <param name="searchOptions">Search options.</param>
+    /// <param name="searchOptions">Search options with legacy TextSearchFilter.</param>
     /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
     private async IAsyncEnumerable<VectorSearchResult<TRecord>> ExecuteVectorSearchAsync(string query, TextSearchOptions? searchOptions, [EnumeratorCancellation] CancellationToken cancellationToken)
     {
         searchOptions ??= new TextSearchOptions();
+
         var vectorSearchOptions = new VectorSearchOptions<TRecord>
         {
 #pragma warning disable CS0618 // VectorSearchFilter is obsolete
-            OldFilter = searchOptions.Filter?.FilterClauses is not null ? new VectorSearchFilter(searchOptions.Filter.FilterClauses) : null,
-#pragma warning restore CS0618 // VectorSearchFilter is obsolete
+            OldFilter = searchOptions.Filter?.FilterClauses is not null
+                ? new VectorSearchFilter(searchOptions.Filter.FilterClauses)
+                : null,
+#pragma warning restore CS0618
             Skip = searchOptions.Skip,
         };
 

dotnet/src/SemanticKernel.Core/Data/TextSearchBehavior/TextSearchProvider.cs

@@ -1,5 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+#pragma warning disable CS0618 // ITextSearch is obsolete - this class provides backward compatibility
+
 using System;
 using System.Collections.Generic;
 using System.Diagnostics.CodeAnalysis;

dotnet/src/SemanticKernel.Core/Data/TextSearchStore/TextSearchStore.cs

@@ -1,5 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+#pragma warning disable CS0618 // ITextSearch is obsolete - this class provides backward compatibility
+
 using System;
 using System.Collections.Generic;
 using System.Diagnostics.CodeAnalysis;

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

@@ -10,7 +10,9 @@ namespace SemanticKernel.UnitTests.Data;
 /// <summary>
 /// Mock implementation of <see cref="ITextSearch"/>
 /// </summary>
+#pragma warning disable CS0618 // Type or member is obsolete
 internal sealed class MockTextSearch(int count = 3, long totalCount = 30) : ITextSearch
+#pragma warning restore CS0618 // Type or member is obsolete
 {
     /// <inheritdoc/>
     public Task<KernelSearchResults<object>> GetSearchResultsAsync(string query, TextSearchOptions? searchOptions = null, CancellationToken cancellationToken = default)

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

@@ -1,5 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+#pragma warning disable CS0618 // Type or member is obsolete - Testing legacy non-generic ITextSearch interface
+
 using System;
 using System.Collections.Generic;
 using System.Linq;