.Net: feat: Modernize GoogleTextSearch connector with ITextSearch<TRecord> interface (microsoft#10456)

[alzarei]

Modernize GoogleTextSearch connector with ITextSearch interface

Problem Statement

The GoogleTextSearch connector currently only implements the legacy ITextSearch interface, forcing users to use clause-based TextSearchFilter instead of modern type-safe LINQ expressions. This creates runtime errors from property name typos and lacks compile-time validation for Google search operations.

Technical Approach

This PR modernizes the GoogleTextSearch connector to implement the generic ITextSearch interface alongside the existing legacy interface. The implementation provides LINQ-to-Google-API conversion with support for equality, contains, NOT operations, FileFormat filtering, and compound AND expressions.

Implementation Details

Core Changes

• Implement ITextSearch interface with full generic method support
• Add LINQ expression analysis supporting equality, contains, NOT operations, and compound AND expressions
• Map LINQ expressions to Google Custom Search API parameters (exactTerms, orTerms, excludeTerms, fileType, siteSearch)
• Support advanced filtering patterns with type-safe property access

Property Mapping Strategy
The Google Custom Search API supports substantial filtering through predefined parameters:

• exactTerms: Exact title/content match
• siteSearch: Site/domain filtering
• fileType: File extension filtering
• excludeTerms: Negation filtering
• Additional parameters: country restrict, language, date filtering

Code Examples

Before (Legacy Interface)

var options = new TextSearchOptions
{
    Filter = new TextSearchFilter().Equality("siteSearch", "microsoft.com")
};

After (Generic Interface)

// Simple filtering
var options = new TextSearchOptions<GoogleWebPage>
{
    Filter = page => page.DisplayLink.Contains("microsoft.com")
};

// Complex filtering
var complexOptions = new TextSearchOptions<GoogleWebPage>
{
    Filter = page => page.DisplayLink.Contains("microsoft.com") &&
                    page.Title.Contains("AI") &&
                    page.FileFormat == "pdf" &&
                    !page.Snippet.Contains("deprecated")
};

Implementation Benefits

Type Safety & Developer Experience

• Compile-time validation of GoogleWebPage property access
• IntelliSense support for all GoogleWebPage properties
• Eliminates runtime errors from property name typos in filters

Enhanced Filtering Capabilities

• Equality filtering: page.Property == "value"
• Contains filtering: page.Property.Contains("text")
• NOT operations: !page.Property.Contains("text")
• FileFormat filtering: page.FileFormat == "pdf"
• Compound AND expressions with multiple conditions

Validation Results

Build Verification

• Command: dotnet build --configuration Release --interactive
• Result: Build succeeded in 3451.8s (57.5 minutes) - all projects compiled successfully
• Status: ✅ PASSED (0 errors, 0 warnings)

Test Results
Full Test Suite:

• Passed: 7,177 (core functionality tests)
• Failed: 2,421 (external API configuration issues)
• Skipped: 31
• Duration: 4 minutes 57 seconds

Core Unit Tests:

• Semantic Kernel unit tests: 1,574/1,574 tests passed (100%)
• Google Connector Tests: 29 tests passed (23 legacy + 6 generic)

Test Failure Analysis
The 2,421 test failures are infrastructure/configuration issues, not code defects:

• Azure OpenAI API Configuration: Missing API keys for external service integration tests
• AWS Bedrock Configuration: Integration tests requiring live AWS services
• Docker Dependencies: Vector database containers not available in development environment
• External Service Dependencies: Integration tests requiring live API services (Bing, Google, etc.)

These failures are expected in development environments without external API configurations.

Method Ambiguity Resolution
Fixed compilation issues when both legacy and generic interfaces are implemented:

// Before (ambiguous):
await textSearch.SearchAsync("query", new() { Top = 4, Skip = 0 });

// After (explicit):
await textSearch.SearchAsync("query", new TextSearchOptions { Top = 4, Skip = 0 });

Files Modified

dotnet/src/Plugins/Plugins.Web/Google/GoogleWebPage.cs (NEW)
dotnet/src/Plugins/Plugins.Web/Google/GoogleTextSearch.cs (MODIFIED)
dotnet/samples/Concepts/TextSearch/Google_TextSearch.cs (ENHANCED)
dotnet/samples/GettingStartedWithTextSearch/Step1_Web_Search.cs (FIXED)

Breaking Changes

None. All existing GoogleTextSearch functionality preserved. Method ambiguity issues resolved through explicit typing.

Multi-PR Context

This is PR 4 of 6 in the structured implementation approach for Issue #10456. This PR extends LINQ filtering support to the GoogleTextSearch connector, following the established pattern from BingTextSearch modernization.

[westey-m]

Some tests to verify the filter url that is created from the different linq expressions would be good.
I'm assuming these tests are just checking that the code doesn't fail, but doesn't actually verify the output filter query is correct?

[westey-m]

Would it make sense to have the return type here be Task<KernelSearchResults<GoogleWebPage>>.
So on ITextSearch<TRecord> it would be Task<KernelSearchResults<TRecord>>

[alzarei]

@westey-m - Thank you for catching this! Correct observation about the return type.

Current Issue

Task<KernelSearchResults<object>> GetSearchResultsAsync(...)  // Forces casting

Fix

I'll create a separate PR to fix the interface (since we're targeting a feature branch), then rebase this PR onto it.

Plan:

1. New PR: Update interface to return KernelSearchResults<TRecord>
2. This PR: Rebase and implement with correct type
3. Other PRs: Rebase onto interface fix

Benefits:

• Eliminates casting overhead
• Provides type safety and IntelliSense
• Keeps interface change isolated for clean rebases

After fix:

// Before
KernelSearchResults<object> results = await search.GetSearchResultsAsync(...);
var page = (GoogleWebPage)results.Results.First();

// After
KernelSearchResults<GoogleWebPage> results = await search.GetSearchResultsAsync(...);
var page = results.Results.First();

Will create the interface fix PR first.

---

Thoughts?

[alzarei]

PR created: #13318

[westey-m]

I'm sure it's fine to check in this one in first as well, and then fix after, just as you wish. I'll check out the other PR as well anyway.

[alzarei]

Rebased on top of feature branch to resolve conflicts. Ready for review.