Mark ITextSearch as obsolete per deprecation pattern

alzarei · alzarei · commit e333850c3c98 · 2025-10-24T23:39:46.000-07:00
- Add [Obsolete] attribute to ITextSearch interface
- Add pragma suppressions in production classes for backward compatibility
- Add pragma suppressions in test/sample files
- Follows Microsoft pattern: introduce new API, deprecate old
- ITextSearch&lt;TRecord&gt; is the replacement with LINQ filtering

Build: 0 errors, 0 warnings
Tests: 1,581 passed
diff --git a/dotnet/samples/GettingStartedWithTextSearch/Step1_Web_Search.cs b/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;
diff --git a/dotnet/samples/GettingStartedWithTextSearch/Step2_Search_For_RAG.cs b/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;
diff --git a/dotnet/src/IntegrationTests/Agents/CommonInterfaceConformance/AgentWithTextSearchProviderConformance/AgentWithTextSearchProvider.cs b/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>(),
diff --git a/dotnet/src/IntegrationTests/Connectors/Memory/AzureAISearch/AzureAISearchTextSearchTests.cs b/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;
diff --git a/dotnet/src/IntegrationTests/Connectors/Memory/InMemory/InMemoryVectorStoreTextSearchTests.cs b/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;
diff --git a/dotnet/src/IntegrationTests/Connectors/Memory/Qdrant/QdrantTextSearchTests.cs b/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;
diff --git a/dotnet/src/IntegrationTests/Data/BaseTextSearchTests.cs b/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;
diff --git a/dotnet/src/IntegrationTests/Plugins/Web/Bing/BingTextSearchTests.cs b/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;
diff --git a/dotnet/src/IntegrationTests/Plugins/Web/Google/GoogleTextSearchTests.cs b/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;
diff --git a/dotnet/src/IntegrationTests/Plugins/Web/Tavily/TavilyTextSearchTests.cs b/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;
diff --git a/dotnet/src/Plugins/Plugins.UnitTests/Web/Bing/BingTextSearchTests.cs b/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;
diff --git a/dotnet/src/Plugins/Plugins.UnitTests/Web/Brave/BraveTextSearchTests.cs b/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;
diff --git a/dotnet/src/Plugins/Plugins.UnitTests/Web/Google/GoogleTextSearchTests.cs b/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;
diff --git a/dotnet/src/Plugins/Plugins.UnitTests/Web/Tavily/TavilyTextSearchTests.cs b/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;
diff --git a/dotnet/src/Plugins/Plugins.Web/Bing/BingTextSearch.cs b/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.
diff --git a/dotnet/src/Plugins/Plugins.Web/Brave/BraveTextSearch.cs b/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.
diff --git a/dotnet/src/Plugins/Plugins.Web/Google/GoogleTextSearch.cs b/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.
diff --git a/dotnet/src/Plugins/Plugins.Web/Tavily/TavilyTextSearch.cs b/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.
diff --git a/dotnet/src/Plugins/Plugins.Web/WebServiceCollectionExtensions.cs b/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;
diff --git a/dotnet/src/SemanticKernel.Abstractions/Data/TextSearch/ITextSearch.cs b/dotnet/src/SemanticKernel.Abstractions/Data/TextSearch/ITextSearch.cs
@@ -1,8 +1,6 @@
 ﻿// Copyright (c) Microsoft. All rights reserved.
 
 using System.Diagnostics.CodeAnalysis;
-using System.Threading;
-using System.Threading.Tasks;
 
 namespace Microsoft.SemanticKernel.Data;
 
@@ -19,71 +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);
 }
diff --git a/dotnet/src/SemanticKernel.AotTests/UnitTests/Search/MockTextSearch.cs b/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;
diff --git a/dotnet/src/SemanticKernel.AotTests/UnitTests/Search/TextSearchExtensionsTests.cs b/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);
diff --git a/dotnet/src/SemanticKernel.Core/Data/TextSearch/TextSearchExtensions.cs b/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;
diff --git a/dotnet/src/SemanticKernel.Core/Data/TextSearch/VectorStoreTextSearch.cs b/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>
diff --git a/dotnet/src/SemanticKernel.Core/Data/TextSearchBehavior/TextSearchProvider.cs b/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;
diff --git a/dotnet/src/SemanticKernel.Core/Data/TextSearchStore/TextSearchStore.cs b/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;
diff --git a/dotnet/src/SemanticKernel.UnitTests/Data/MockTextSearch.cs b/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)
diff --git a/dotnet/src/SemanticKernel.UnitTests/Data/TextSearchProviderTests.cs b/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;
