.Net: Use interfaces for mapper abstractions (#8424)

### Motivation and Context

Closes #8390 

### Description

<!-- Describe your changes, the overall approach, the underlying design.
These notes will help understanding how your code works. Thanks! -->

### Contribution Checklist

<!-- Before submitting this PR, please make sure: -->

- [ ] The code builds clean without any errors or warnings
- [ ] The PR follows the [SK Contribution
Guidelines](https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md)
and the [pre-submission formatting
script](https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md#development-scripts)
raises no violations
- [ ] All unit tests pass, and I have added new tests where possible
- [ ] I didn't break anyone 😄

dotnet/samples/Concepts/Search/Bing_FunctionCallingWithTextSearch.cs

@@ -125,7 +125,7 @@ public async Task FunctionCallingWithBingTextSearchUsingSiteArgumentAsync()
         Console.WriteLine(await kernel.InvokePromptAsync("What is the Semantic Kernel? Only include results from techcommunity.microsoft.com. Include citations to the relevant information where it is referenced in the response.", arguments));
     }
 
-    private static KernelFunction CreateSearchBySite(BingTextSearch textSearch, BasicFilterOptions? basicFilter = null, MapSearchResultToString? mapToString = null)
+    private static KernelFunction CreateSearchBySite(BingTextSearch textSearch, BasicFilterOptions? basicFilter = null)
     {
         var options = new KernelFunctionFromMethodOptions()
         {

dotnet/samples/Concepts/Search/Bing_TextSearch.cs

@@ -74,7 +74,7 @@ public async Task UsingBingTextSearchWithACustomMapperAsync()
         var textSearch = new BingTextSearch(apiKey: TestConfiguration.Bing.ApiKey, options: new()
         {
             HttpClient = httpClient,
-            MapToString = webPage => JsonSerializer.Serialize(webPage),
+            StringMapper = new TestTextSearchStringMapper(),
         });
 
         var query = "What is the Semantic Kernel?";
@@ -103,7 +103,7 @@ public async Task UsingBingTextSearchWithASiteFilterAsync()
         var textSearch = new BingTextSearch(apiKey: TestConfiguration.Bing.ApiKey, options: new()
         {
             HttpClient = httpClient,
-            MapToString = webPage => JsonSerializer.Serialize(webPage),
+            StringMapper = new TestTextSearchStringMapper(),
         });
 
         var query = "What is the Semantic Kernel?";
@@ -121,5 +121,17 @@ public async Task UsingBingTextSearchWithASiteFilterAsync()
 
     #region private
     private const int HorizontalRuleLength = 80;
+
+    /// <summary>
+    /// Test mapper which converts an arbitrary search result to a string using JSON serialization.
+    /// </summary>
+    private sealed class TestTextSearchStringMapper : ITextSearchStringMapper
+    {
+        /// <inheritdoc />
+        public string MapFromResultToString(object result)
+        {
+            return JsonSerializer.Serialize(result);
+        }
+    }
     #endregion
 }

dotnet/samples/Concepts/Search/Google_TextSearch.cs

@@ -69,7 +69,7 @@ public async Task UsingGoogleTextSearchWithACustomMapperAsync()
         var textSearch = new GoogleTextSearch(
             searchEngineId: TestConfiguration.Google.SearchEngineId,
             apiKey: TestConfiguration.Google.ApiKey,
-            options: new() { MapToString = webPage => JsonSerializer.Serialize(webPage) });
+            options: new() { StringMapper = new TestTextSearchStringMapper() });
 
         var query = "What is the Semantic Kernel?";
 
@@ -110,6 +110,18 @@ public async Task UsingGoogleTextSearchWithASiteSearchFilterAsync()
     #region private
     private const int HorizontalRuleLength = 80;
 
+    /// <summary>
+    /// Test mapper which converts an arbitrary search result to a string using JSON serialization.
+    /// </summary>
+    private sealed class TestTextSearchStringMapper : ITextSearchStringMapper
+    {
+        /// <inheritdoc />
+        public string MapFromResultToString(object result)
+        {
+            return JsonSerializer.Serialize(result);
+        }
+    }
+
     /// <summary>
     /// Implementation of <see cref="ConfigurableMessageHandler"/> which logs HTTP responses.
     /// </summary>

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

@@ -104,13 +104,13 @@ public async Task GetSearchResultsReturnsSuccessfullyAsync()
     }
 
     [Fact]
-    public async Task SearchWithCustomMapperReturnsSuccessfullyAsync()
+    public async Task SearchWithCustomStringMapperReturnsSuccessfullyAsync()
     {
         // Arrange
         this._messageHandlerStub.AddJsonResponse(File.ReadAllText(WhatIsTheSKResponseJson));
 
         // Create an ITextSearch instance using Bing search
-        var textSearch = new BingTextSearch(apiKey: "ApiKey", options: new() { HttpClient = this._httpClient, MapToString = webPage => JsonSerializer.Serialize(webPage) });
+        var textSearch = new BingTextSearch(apiKey: "ApiKey", options: new() { HttpClient = this._httpClient, StringMapper = new TestTextSearchStringMapper() });
 
         // Act
         KernelSearchResults<string> result = await textSearch.SearchAsync("What is the Semantic Kernel?", new() { Count = 10, Offset = 0 });
@@ -129,6 +129,33 @@ public async Task SearchWithCustomMapperReturnsSuccessfullyAsync()
         }
     }
 
+    [Fact]
+    public async Task GetTextSearchResultsWithCustomResultMapperReturnsSuccessfullyAsync()
+    {
+        // Arrange
+        this._messageHandlerStub.AddJsonResponse(File.ReadAllText(WhatIsTheSKResponseJson));
+
+        // Create an ITextSearch instance using Bing search
+        var textSearch = new BingTextSearch(apiKey: "ApiKey", options: new() { HttpClient = this._httpClient, ResultMapper = new TestTextSearchResultMapper() });
+
+        // Act
+        KernelSearchResults<TextSearchResult> result = await textSearch.GetTextSearchResultsAsync("What is the Semantic Kernel?", new() { Count = 10, Offset = 0 });
+
+        // Assert
+        Assert.NotNull(result);
+        Assert.NotNull(result.Results);
+        var resultList = await result.Results.ToListAsync();
+        Assert.NotNull(resultList);
+        Assert.Equal(10, resultList.Count);
+        foreach (var textSearchResult in resultList)
+        {
+            Assert.NotNull(textSearchResult);
+            Assert.Equal(textSearchResult.Name, textSearchResult.Name?.ToUpperInvariant());
+            Assert.Equal(textSearchResult.Value, textSearchResult.Value?.ToUpperInvariant());
+            Assert.Equal(textSearchResult.Link, textSearchResult.Link?.ToUpperInvariant());
+        }
+    }
+
     [Theory]
     [InlineData("answerCount", 5, "https://api.bing.microsoft.com/v7.0/search?q=What%20is%20the%20Semantic%20Kernel%3F&count=4&offset=0&answerCount=5")]
     [InlineData("cc", "AR", "https://api.bing.microsoft.com/v7.0/search?q=What%20is%20the%20Semantic%20Kernel%3F&count=4&offset=0&cc=AR")]
@@ -205,5 +232,39 @@ public void Dispose()
     private readonly MultipleHttpMessageHandlerStub _messageHandlerStub;
     private readonly HttpClient _httpClient;
     private readonly Kernel _kernel;
+
+    /// <summary>
+    /// Test mapper which converts a BingWebPage search result to a string using JSON serialization.
+    /// </summary>
+    private sealed class TestTextSearchStringMapper : ITextSearchStringMapper
+    {
+        /// <inheritdoc />
+        public string MapFromResultToString(object result)
+        {
+            return JsonSerializer.Serialize(result);
+        }
+    }
+
+    /// <summary>
+    /// Test mapper which converts a BingWebPage search result to a string using JSON serialization.
+    /// </summary>
+    private sealed class TestTextSearchResultMapper : ITextSearchResultMapper
+    {
+        /// <inheritdoc />
+        public TextSearchResult MapFromResultToTextSearchResult(object result)
+        {
+            if (result is not BingWebPage webPage)
+            {
+                throw new ArgumentException("Result must be a BingWebPage", nameof(result));
+            }
+
+            return new TextSearchResult
+            {
+                Name = webPage.Name?.ToUpperInvariant(),
+                Value = webPage.Snippet?.ToUpperInvariant(),
+                Link = webPage.DisplayUrl?.ToUpperInvariant(),
+            };
+        }
+    }
     #endregion
 }

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

@@ -3,6 +3,7 @@
 using System;
 using System.IO;
 using System.Linq;
+using System.Text.Json;
 using System.Threading.Tasks;
 using Google.Apis.CustomSearchAPI.v1.Data;
 using Google.Apis.Http;
@@ -109,6 +110,65 @@ public async Task GetSearchResultsReturnsSuccessfullyAsync()
         }
     }
 
+    [Fact]
+    public async Task SearchWithCustomStringMapperReturnsSuccessfullyAsync()
+    {
+        // Arrange
+        this._messageHandlerStub.AddJsonResponse(File.ReadAllText(WhatIsTheSKResponseJson));
+
+        // Create an ITextSearch instance using Google search
+        using var textSearch = new GoogleTextSearch(
+            initializer: new() { ApiKey = "ApiKey", HttpClientFactory = this._clientFactory },
+            searchEngineId: "SearchEngineId",
+            options: new() { StringMapper = new TestTextSearchStringMapper() });
+
+        // Act
+        KernelSearchResults<string> result = await textSearch.SearchAsync("What is the Semantic Kernel?", new() { Count = 4, Offset = 0 });
+
+        // Assert
+        Assert.NotNull(result);
+        Assert.NotNull(result.Results);
+        var resultList = await result.Results.ToListAsync();
+        Assert.NotNull(resultList);
+        Assert.Equal(4, resultList.Count);
+        foreach (var stringResult in resultList)
+        {
+            Assert.NotEmpty(stringResult);
+            var googleResult = JsonSerializer.Deserialize<global::Google.Apis.CustomSearchAPI.v1.Data.Result>(stringResult);
+            Assert.NotNull(googleResult);
+        }
+    }
+
+    [Fact]
+    public async Task GetTextSearchResultsWithCustomResultMapperReturnsSuccessfullyAsync()
+    {
+        // Arrange
+        this._messageHandlerStub.AddJsonResponse(File.ReadAllText(WhatIsTheSKResponseJson));
+
+        // Create an ITextSearch instance using Google search
+        using var textSearch = new GoogleTextSearch(
+            initializer: new() { ApiKey = "ApiKey", HttpClientFactory = this._clientFactory },
+            searchEngineId: "SearchEngineId",
+            options: new() { ResultMapper = new TestTextSearchResultMapper() });
+
+        // Act
+        KernelSearchResults<TextSearchResult> result = await textSearch.GetTextSearchResultsAsync("What is the Semantic Kernel?", new() { Count = 4, Offset = 0 });
+
+        // Assert
+        Assert.NotNull(result);
+        Assert.NotNull(result.Results);
+        var resultList = await result.Results.ToListAsync();
+        Assert.NotNull(resultList);
+        Assert.Equal(4, resultList.Count);
+        foreach (var textSearchResult in resultList)
+        {
+            Assert.NotNull(textSearchResult);
+            Assert.Equal(textSearchResult.Name, textSearchResult.Name?.ToUpperInvariant());
+            Assert.Equal(textSearchResult.Value, textSearchResult.Value?.ToUpperInvariant());
+            Assert.Equal(textSearchResult.Link, textSearchResult.Link?.ToUpperInvariant());
+        }
+    }
+
     [Theory]
     [InlineData("cr", "countryAF", "https://customsearch.googleapis.com/customsearch/v1?key=ApiKey&cr=countryAF&cx=SearchEngineId&num=4&q=What%20is%20the%20Semantic%20Kernel%3F&start=0")]
     [InlineData("dateRestrict", "d[5]", "https://customsearch.googleapis.com/customsearch/v1?key=ApiKey&cx=SearchEngineId&dateRestrict=d%5B5%5D&num=4&q=What%20is%20the%20Semantic%20Kernel%3F&start=0")]
@@ -197,5 +257,39 @@ public void Dispose()
             GC.SuppressFinalize(this);
         }
     }
+
+    /// <summary>
+    /// Test mapper which converts a global::Google.Apis.CustomSearchAPI.v1.Data.Result search result to a string using JSON serialization.
+    /// </summary>
+    private sealed class TestTextSearchStringMapper : ITextSearchStringMapper
+    {
+        /// <inheritdoc />
+        public string MapFromResultToString(object result)
+        {
+            return JsonSerializer.Serialize(result);
+        }
+    }
+
+    /// <summary>
+    /// Test mapper which converts a global::Google.Apis.CustomSearchAPI.v1.Data.Result search result to a string using JSON serialization.
+    /// </summary>
+    private sealed class TestTextSearchResultMapper : ITextSearchResultMapper
+    {
+        /// <inheritdoc />
+        public TextSearchResult MapFromResultToTextSearchResult(object result)
+        {
+            if (result is not global::Google.Apis.CustomSearchAPI.v1.Data.Result googleResult)
+            {
+                throw new ArgumentException("Result must be a Google Result", nameof(result));
+            }
+
+            return new TextSearchResult
+            {
+                Name = googleResult.Title?.ToUpperInvariant(),
+                Value = googleResult.Snippet?.ToUpperInvariant(),
+                Link = googleResult.Link?.ToUpperInvariant(),
+            };
+        }
+    }
     #endregion
 }

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

@@ -36,12 +36,12 @@ public BingTextSearch(string apiKey, BingTextSearchOptions? options = null)
         this._httpClient = options?.HttpClient ?? HttpClientProvider.GetHttpClient();
         this._httpClient.DefaultRequestHeaders.Add("User-Agent", HttpHeaderConstant.Values.UserAgent);
         this._httpClient.DefaultRequestHeaders.Add(HttpHeaderConstant.Names.SemanticKernelVersion, HttpHeaderConstant.Values.GetAssemblyVersion(typeof(BingTextSearch)));
-        this._mapToString = options?.MapToString ?? DefaultMapToString;
-        this._mapToTextSearchResult = options?.MapToTextSearchResult ?? DefaultMapToTextSearchResult;
+        this._stringMapper = options?.StringMapper ?? s_defaultStringMapper;
+        this._resultMapper = options?.ResultMapper ?? s_defaultResultMapper;
     }
 
     /// <inheritdoc/>
-    async public Task<KernelSearchResults<string>> SearchAsync(string query, TextSearchOptions? searchOptions = null, CancellationToken cancellationToken = default)
+    public async Task<KernelSearchResults<string>> SearchAsync(string query, TextSearchOptions? searchOptions = null, CancellationToken cancellationToken = default)
     {
         searchOptions ??= new TextSearchOptions();
         BingSearchResponse<BingWebPage>? searchResponse = await this.ExecuteSearchAsync(query, searchOptions, cancellationToken).ConfigureAwait(false);
@@ -52,7 +52,7 @@ async public Task<KernelSearchResults<string>> SearchAsync(string query, TextSea
     }
 
     /// <inheritdoc/>
-    async public Task<KernelSearchResults<TextSearchResult>> GetTextSearchResultsAsync(string query, TextSearchOptions? searchOptions = null, CancellationToken cancellationToken = default)
+    public async Task<KernelSearchResults<TextSearchResult>> GetTextSearchResultsAsync(string query, TextSearchOptions? searchOptions = null, CancellationToken cancellationToken = default)
     {
         searchOptions ??= new TextSearchOptions();
         BingSearchResponse<BingWebPage>? searchResponse = await this.ExecuteSearchAsync(query, searchOptions, cancellationToken).ConfigureAwait(false);
@@ -63,7 +63,7 @@ async public Task<KernelSearchResults<TextSearchResult>> GetTextSearchResultsAsy
     }
 
     /// <inheritdoc/>
-    async public Task<KernelSearchResults<object>> GetSearchResultsAsync(string query, TextSearchOptions? searchOptions = null, CancellationToken cancellationToken = default)
+    public async Task<KernelSearchResults<object>> GetSearchResultsAsync(string query, TextSearchOptions? searchOptions = null, CancellationToken cancellationToken = default)
     {
         searchOptions ??= new TextSearchOptions();
         BingSearchResponse<BingWebPage>? searchResponse = await this.ExecuteSearchAsync(query, searchOptions, cancellationToken).ConfigureAwait(false);
@@ -79,8 +79,11 @@ async public Task<KernelSearchResults<object>> GetSearchResultsAsync(string quer
     private readonly HttpClient _httpClient;
     private readonly string? _apiKey;
     private readonly Uri? _uri = null;
-    private readonly MapBingWebPageToString _mapToString;
-    private readonly MapBingWebPageToTextSearchResult _mapToTextSearchResult;
+    private readonly ITextSearchStringMapper _stringMapper;
+    private readonly ITextSearchResultMapper _resultMapper;
+
+    private static readonly ITextSearchStringMapper s_defaultStringMapper = new DefaultTextSearchStringMapper();
+    private static readonly ITextSearchResultMapper s_defaultResultMapper = new DefaultTextSearchResultMapper();
 
     // See https://learn.microsoft.com/en-us/bing/search-apis/bing-web-search/reference/query-parameters
     private static readonly string[] s_queryParameters = ["answerCount", "cc", "freshness", "mkt", "promote", "responseFilter", "safeSearch", "setLang", "textDecorations", "textFormat"];
@@ -170,7 +173,7 @@ private async IAsyncEnumerable<TextSearchResult> GetResultsAsTextSearchResultAsy
 
         foreach (var webPage in searchResponse.WebPages.Value)
         {
-            yield return this._mapToTextSearchResult(webPage);
+            yield return this._resultMapper.MapFromResultToTextSearchResult(webPage);
             await Task.Yield();
         }
     }
@@ -189,7 +192,7 @@ private async IAsyncEnumerable<string> GetResultsAsStringAsync(BingSearchRespons
 
         foreach (var webPage in searchResponse.WebPages.Value)
         {
-            yield return this._mapToString(webPage);
+            yield return this._stringMapper.MapFromResultToString(webPage);
             await Task.Yield();
         }
     }
@@ -211,17 +214,35 @@ private async IAsyncEnumerable<string> GetResultsAsStringAsync(BingSearchRespons
     /// <summary>
     /// Default implementation which maps from a <see cref="BingWebPage"/> to a <see cref="string"/>
     /// </summary>
-    private static string DefaultMapToString(BingWebPage webPage)
+    private sealed class DefaultTextSearchStringMapper : ITextSearchStringMapper
     {
-        return webPage.Snippet ?? string.Empty;
+        /// <inheritdoc />
+        public string MapFromResultToString(object result)
+        {
+            if (result is not BingWebPage webPage)
+            {
+                throw new ArgumentException("Result must be a BingWebPage", nameof(result));
+            }
+
+            return webPage.Snippet ?? string.Empty;
+        }
     }
 
     /// <summary>
     /// Default implementation which maps from a <see cref="BingWebPage"/> to a <see cref="TextSearchResult"/>
     /// </summary>
-    private static TextSearchResult DefaultMapToTextSearchResult(BingWebPage webPage)
+    private sealed class DefaultTextSearchResultMapper : ITextSearchResultMapper
     {
-        return new TextSearchResult(webPage.Name, webPage.Snippet, webPage.Url);
+        /// <inheritdoc />
+        public TextSearchResult MapFromResultToTextSearchResult(object result)
+        {
+            if (result is not BingWebPage webPage)
+            {
+                throw new ArgumentException("Result must be a BingWebPage", nameof(result));
+            }
+
+            return new TextSearchResult(webPage.Name, webPage.Snippet, webPage.Url);
+        }
     }
 
     /// <summary>