feat: enhance GoogleTextSearch LINQ filtering with Contains support

- Add Contains() operation support for string properties (Title, Snippet, Link)
- Implement intelligent mapping: Contains() -> orTerms for flexible matching
- Add 2 new test methods to validate LINQ filtering with Contains and equality
- Fix method ambiguity (CS0121) in GoogleTextSearchTests by using explicit TextSearchOptions types
- Fix method ambiguity in Google_TextSearch.cs sample by specifying explicit option types
- Enhance error messages with clear guidance on supported LINQ patterns and properties

This enhancement extends the basic LINQ filtering (equality only) to include
string Contains operations, providing more natural and flexible filtering
patterns while staying within Google Custom Search API capabilities.

All tests passing: 25/25 Google tests (22 existing + 3 new)

Author: alzarei

dotnet/samples/Concepts/Search/Google_TextSearch.cs

@@ -26,7 +26,7 @@ public async Task UsingGoogleTextSearchAsync()
         var query = "What is the Semantic Kernel?";
 
         // Search and return results as string items
-        KernelSearchResults<string> stringResults = await textSearch.SearchAsync(query, new() { Top = 4, Skip = 0 });
+        KernelSearchResults<string> stringResults = await textSearch.SearchAsync(query, new TextSearchOptions { Top = 4, Skip = 0 });
         Console.WriteLine("——— String Results ———\n");
         await foreach (string result in stringResults.Results)
         {
@@ -35,7 +35,7 @@ public async Task UsingGoogleTextSearchAsync()
         }
 
         // Search and return results as TextSearchResult items
-        KernelSearchResults<TextSearchResult> textResults = await textSearch.GetTextSearchResultsAsync(query, new() { Top = 4, Skip = 4 });
+        KernelSearchResults<TextSearchResult> textResults = await textSearch.GetTextSearchResultsAsync(query, new TextSearchOptions { Top = 4, Skip = 4 });
         Console.WriteLine("\n——— Text Search Results ———\n");
         await foreach (TextSearchResult result in textResults.Results)
         {
@@ -46,7 +46,7 @@ public async Task UsingGoogleTextSearchAsync()
         }
 
         // Search and return results as Google.Apis.CustomSearchAPI.v1.Data.Result items
-        KernelSearchResults<object> fullResults = await textSearch.GetSearchResultsAsync(query, new() { Top = 4, Skip = 8 });
+        KernelSearchResults<object> fullResults = await textSearch.GetSearchResultsAsync(query, new TextSearchOptions { Top = 4, Skip = 8 });
         Console.WriteLine("\n——— Google Web Page Results ———\n");
         await foreach (Google.Apis.CustomSearchAPI.v1.Data.Result result in fullResults.Results)
         {
@@ -74,7 +74,7 @@ public async Task UsingGoogleTextSearchWithACustomMapperAsync()
         var query = "What is the Semantic Kernel?";
 
         // Search with TextSearchResult textResult type
-        KernelSearchResults<string> stringResults = await textSearch.SearchAsync(query, new() { Top = 2, Skip = 0 });
+        KernelSearchResults<string> stringResults = await textSearch.SearchAsync(query, new TextSearchOptions { Top = 2, Skip = 0 });
         Console.WriteLine("--- Serialized JSON Results ---");
         await foreach (string result in stringResults.Results)
         {

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

@@ -318,6 +318,60 @@ public async Task GenericGetSearchResultsReturnsSuccessfullyAsync()
         }
     }
 
+    [Fact]
+    public async Task GenericSearchWithContainsFilterReturnsSuccessfullyAsync()
+    {
+        // Arrange
+        this._messageHandlerStub.AddJsonResponse(File.ReadAllText(WhatIsTheSKResponseJson));
+
+        using var textSearch = new GoogleTextSearch(
+            initializer: new() { ApiKey = "ApiKey", HttpClientFactory = this._clientFactory },
+            searchEngineId: "SearchEngineId");
+
+        // Act - Use generic interface with Contains filtering
+        KernelSearchResults<string> result = await textSearch.SearchAsync("What is the Semantic Kernel?",
+            new TextSearchOptions<GoogleWebPage>
+            {
+                Top = 4,
+                Skip = 0,
+                Filter = page => page.Title.Contains("Semantic")
+            });
+
+        // Assert
+        Assert.NotNull(result);
+        Assert.NotNull(result.Results);
+        var resultList = await result.Results.ToListAsync();
+        Assert.NotNull(resultList);
+        Assert.Equal(4, resultList.Count);
+    }
+
+    [Fact]
+    public async Task GenericSearchWithEqualityFilterReturnsSuccessfullyAsync()
+    {
+        // Arrange
+        this._messageHandlerStub.AddJsonResponse(File.ReadAllText(WhatIsTheSKResponseJson));
+
+        using var textSearch = new GoogleTextSearch(
+            initializer: new() { ApiKey = "ApiKey", HttpClientFactory = this._clientFactory },
+            searchEngineId: "SearchEngineId");
+
+        // Act - Use generic interface with equality filtering
+        KernelSearchResults<string> result = await textSearch.SearchAsync("What is the Semantic Kernel?",
+            new TextSearchOptions<GoogleWebPage>
+            {
+                Top = 4,
+                Skip = 0,
+                Filter = page => page.DisplayLink == "microsoft.com"
+            });
+
+        // Assert
+        Assert.NotNull(result);
+        Assert.NotNull(result.Results);
+        var resultList = await result.Results.ToListAsync();
+        Assert.NotNull(resultList);
+        Assert.Equal(4, resultList.Count);
+    }
+
     /// <inheritdoc/>
     public void Dispose()
     {

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

@@ -148,22 +148,21 @@ private static TextSearchOptions ConvertToLegacyOptions(TextSearchOptions<Google
 
     /// <summary>
     /// Converts a LINQ expression to a TextSearchFilter compatible with Google Custom Search API.
-    /// Only supports simple property equality expressions that map to Google's filter capabilities.
+    /// Supports property equality expressions and string Contains operations that map to Google's filter capabilities.
     /// </summary>
     /// <param name="linqExpression">The LINQ expression to convert.</param>
     /// <returns>A TextSearchFilter with equivalent filtering.</returns>
     /// <exception cref="NotSupportedException">Thrown when the expression cannot be converted to Google filters.</exception>
     private static TextSearchFilter ConvertLinqExpressionToGoogleFilter<TRecord>(Expression<Func<TRecord, bool>> linqExpression)
     {
+        // Handle simple equality: record.PropertyName == "value"
         if (linqExpression.Body is BinaryExpression binaryExpr && binaryExpr.NodeType == ExpressionType.Equal)
         {
-            // Handle simple equality: record.PropertyName == "value"
             if (binaryExpr.Left is MemberExpression memberExpr && binaryExpr.Right is ConstantExpression constExpr)
             {
                 string propertyName = memberExpr.Member.Name;
                 object? value = constExpr.Value;
 
-                // Map GoogleWebPage properties to Google API filter names
                 string? googleFilterName = MapPropertyToGoogleFilter(propertyName);
                 if (googleFilterName != null && value != null)
                 {
@@ -172,11 +171,45 @@ private static TextSearchFilter ConvertLinqExpressionToGoogleFilter<TRecord>(Exp
             }
         }
 
+        // Handle string Contains: record.PropertyName.Contains("value")
+        if (linqExpression.Body is MethodCallExpression methodCall &&
+            methodCall.Method.Name == "Contains" &&
+            methodCall.Method.DeclaringType == typeof(string))
+        {
+            if (methodCall.Object is MemberExpression memberExpr &&
+                methodCall.Arguments.Count == 1 &&
+                methodCall.Arguments[0] is ConstantExpression constExpr)
+            {
+                string propertyName = memberExpr.Member.Name;
+                object? value = constExpr.Value;
+
+                string? googleFilterName = MapPropertyToGoogleFilter(propertyName);
+                if (googleFilterName != null && value != null)
+                {
+                    // For Contains operations on text fields, use exactTerms or orTerms
+                    if (googleFilterName == "exactTerms")
+                    {
+                        return new TextSearchFilter().Equality("orTerms", value); // More flexible than exactTerms
+                    }
+                    return new TextSearchFilter().Equality(googleFilterName, value);
+                }
+            }
+        }
+
+        // Generate helpful error message with supported patterns
+        var supportedPatterns = new[]
+        {
+            "page.Property == \"value\" (exact match)",
+            "page.Property.Contains(\"text\") (partial match)"
+        };
+
+        var supportedProperties = s_queryParameters.Select(p =>
+            MapGoogleFilterToProperty(p)).Where(p => p != null).Distinct();
+
         throw new NotSupportedException(
-            "LINQ expression '" + linqExpression + "' cannot be converted to Google API filters. " +
-            "Only simple equality expressions like 'page => page.Title == \"example\"' are supported, " +
-            "and only for properties that map to Google API parameters: " +
-            string.Join(", ", s_queryParameters));
+            $"LINQ expression '{linqExpression}' cannot be converted to Google API filters. " +
+            $"Supported patterns: {string.Join(", ", supportedPatterns)}. " +
+            $"Supported properties: {string.Join(", ", supportedProperties)}.");
     }
 
     /// <summary>
@@ -208,6 +241,27 @@ private static TextSearchFilter ConvertLinqExpressionToGoogleFilter<TRecord>(Exp
         };
     }
 
+    /// <summary>
+    /// Maps Google Custom Search API filter field names back to example GoogleWebPage property names.
+    /// Used for generating helpful error messages.
+    /// </summary>
+    /// <param name="googleFilterName">The Google API filter name.</param>
+    /// <returns>An example property name, or null if not mappable.</returns>
+    private static string? MapGoogleFilterToProperty(string googleFilterName)
+    {
+        return googleFilterName switch
+        {
+            "siteSearch" => "DisplayLink",
+            "exactTerms" => "Title",
+            "filter" => "FileFormat",
+            "hl" => "HL",
+            "gl" => "GL",
+            "cr" => "CR",
+            "lr" => "LR",
+            _ => null
+        };
+    }
+
     #endregion
 
     /// <inheritdoc/>