Quickstart: Use a Bing Web Search .NET client library

Articolo
09/09/2022

The Bing Web Search client library makes it easy to integrate Bing Web Search into your C# application. In this quickstart, you'll learn how to instantiate a client, send a request, and print the response.

Want to see the code right now? Samples for the Bing Search client libraries for .NET are available on GitHub.

Prerequisites

Here are a few things that you'll need before running this quickstart:

Create a project and install dependencies

Tip

Get the latest code as a Visual Studio solution from GitHub.

The first step is to create a new console project. If you need help with setting up a console project, see Hello World -- Your First Program (C# Programming Guide). To use the Bing Web Search SDK in your application, you'll need to install Microsoft.Azure.CognitiveServices.Search.WebSearch using the NuGet Package Manager.

The Web Search SDK package also installs:

Microsoft.Rest.ClientRuntime
Microsoft.Rest.ClientRuntime.Azure
Newtonsoft.Json

Declare dependencies

Open your project in Visual Studio or Visual Studio Code and import these dependencies:

using System;
using System.Collections.Generic;
using Microsoft.Azure.CognitiveServices.Search.WebSearch;
using Microsoft.Azure.CognitiveServices.Search.WebSearch.Models;
using System.Linq;

Create project scaffolding

When you created your new console project, a namespace and class for your application should have been created. Your program should look like this example:

namespace WebSearchSDK
{
    class YOUR_PROGRAM
    {

        // The code in the following sections goes here.

    }
}

In the following sections, we'll build our sample application within this class.

Construct a request

This code constructs the search query.

public static async void WebResults(WebSearchClient client)
{
    try
    {
        var webData = await client.Web.SearchAsync(query: "Yosemite National Park");
        Console.WriteLine("Searching for \"Yosemite National Park\"");

        // Code for handling responses is provided in the next section...

    }
    catch (Exception ex)
    {
        Console.WriteLine("Encountered exception. " + ex.Message);
    }
}

Handle the response

Next, let's add some code to parse the response and print the results. The Name and Url for the first web page, image, news article, and video are printed if present in the response object.

if (webData?.WebPages?.Value?.Count > 0)
{
    // find the first web page
    var firstWebPagesResult = webData.WebPages.Value.FirstOrDefault();

    if (firstWebPagesResult != null)
    {
        Console.WriteLine("Webpage Results # {0}", webData.WebPages.Value.Count);
        Console.WriteLine("First web page name: {0} ", firstWebPagesResult.Name);
        Console.WriteLine("First web page URL: {0} ", firstWebPagesResult.Url);
    }
    else
    {
        Console.WriteLine("Didn't find any web pages...");
    }
}
else
{
    Console.WriteLine("Didn't find any web pages...");
}

/*
 * Images
 * If the search response contains images, the first result's name
 * and url are printed.
 */
if (webData?.Images?.Value?.Count > 0)
{
    // find the first image result
    var firstImageResult = webData.Images.Value.FirstOrDefault();

    if (firstImageResult != null)
    {
        Console.WriteLine("Image Results # {0}", webData.Images.Value.Count);
        Console.WriteLine("First Image result name: {0} ", firstImageResult.Name);
        Console.WriteLine("First Image result URL: {0} ", firstImageResult.ContentUrl);
    }
    else
    {
        Console.WriteLine("Didn't find any images...");
    }
}
else
{
    Console.WriteLine("Didn't find any images...");
}

/*
 * News
 * If the search response contains news articles, the first result's name
 * and url are printed.
 */
if (webData?.News?.Value?.Count > 0)
{
    // find the first news result
    var firstNewsResult = webData.News.Value.FirstOrDefault();

    if (firstNewsResult != null)
    {
        Console.WriteLine("\r\nNews Results # {0}", webData.News.Value.Count);
        Console.WriteLine("First news result name: {0} ", firstNewsResult.Name);
        Console.WriteLine("First news result URL: {0} ", firstNewsResult.Url);
    }
    else
    {
        Console.WriteLine("Didn't find any news articles...");
    }
}
else
{
    Console.WriteLine("Didn't find any news articles...");
}

/*
 * Videos
 * If the search response contains videos, the first result's name
 * and url are printed.
 */
if (webData?.Videos?.Value?.Count > 0)
{
    // find the first video result
    var firstVideoResult = webData.Videos.Value.FirstOrDefault();

    if (firstVideoResult != null)
    {
        Console.WriteLine("\r\nVideo Results # {0}", webData.Videos.Value.Count);
        Console.WriteLine("First Video result name: {0} ", firstVideoResult.Name);
        Console.WriteLine("First Video result URL: {0} ", firstVideoResult.ContentUrl);
    }
    else
    {
        Console.WriteLine("Didn't find any videos...");
    }
}
else
{
    Console.WriteLine("Didn't find any videos...");
}

Declare the main method

In this application, the main method includes code that instantiates the client, validates the subscriptionKey, and calls WebResults. Make sure that you enter a valid subscription key for your Azure account before continuing.

static void Main(string[] args)
{
    var client = new WebSearchClient(new ApiKeyServiceClientCredentials("YOUR_SUBSCRIPTION_KEY"));

    WebResults(client);

    Console.WriteLine("Press any key to exit...");
    Console.ReadKey();
}

Run the application

Let's run the application!

dotnet run

Define functions and filter results

Now that you've made your first call to the Bing Web Search API, let's look at a few functions that highlight SDK functionality for refining queries and filtering results. Each function can be added to your C# application created in the previous section.

Limit the number of results returned by Bing

This sample uses the count and offset parameters to limit the number of results returned for "Best restaurants in Seattle". The Name and Url for the first result are printed.

Add this code to your console project:

public static async void WebResultsWithCountAndOffset(WebSearchClient client)
{
    try
    {
        var webData = await client.Web.SearchAsync(query: "Best restaurants in Seattle", offset: 10, count: 20);
        Console.WriteLine("\r\nSearching for \" Best restaurants in Seattle \"");

        if (webData?.WebPages?.Value?.Count > 0)
        {
            var firstWebPagesResult = webData.WebPages.Value.FirstOrDefault();

            if (firstWebPagesResult != null)
            {
                Console.WriteLine("Web Results #{0}", webData.WebPages.Value.Count);
                Console.WriteLine("First web page name: {0} ", firstWebPagesResult.Name);
                Console.WriteLine("First web page URL: {0} ", firstWebPagesResult.Url);
            }
            else
            {
                Console.WriteLine("Couldn't find first web result!");
            }
        }
        else
        {
            Console.WriteLine("Didn't see any Web data..");
        }
    }
    catch (Exception ex)
    {
        Console.WriteLine("Encountered exception. " + ex.Message);
    }
}

Add WebResultsWithCountAndOffset to main:

static void Main(string[] args)
{
    var client = new WebSearchClient(new ApiKeyServiceClientCredentials("YOUR_SUBSCRIPTION_KEY"));

    WebResults(client);
    // Search with count and offset...
    WebResultsWithCountAndOffset(client);  

    Console.WriteLine("Press any key to exit...");
    Console.ReadKey();
}

Run the application.

Filter for news

This sample uses the response_filter parameter to filter search results. The search results returned are limited to news articles for "Microsoft". The Name and Url for the first result are printed.

Add this code to your console project:

public static async void WebSearchWithResponseFilter(WebSearchClient client)
{
    try
    {
        IList<string> responseFilterstrings = new List<string>() { "news" };
        var webData = await client.Web.SearchAsync(query: "Microsoft", responseFilter: responseFilterstrings);
        Console.WriteLine("\r\nSearching for \" Microsoft \" with response filter \"news\"");

        if (webData?.News?.Value?.Count > 0)
        {
            var firstNewsResult = webData.News.Value.FirstOrDefault();

            if (firstNewsResult != null)
            {
                Console.WriteLine("News Results #{0}", webData.News.Value.Count);
                Console.WriteLine("First news result name: {0} ", firstNewsResult.Name);
                Console.WriteLine("First news result URL: {0} ", firstNewsResult.Url);
            }
            else
            {
                Console.WriteLine("Couldn't find first News results!");
            }
        }
        else
        {
            Console.WriteLine("Didn't see any News data..");
        }

    }
    catch (Exception ex)
    {
        Console.WriteLine("Encountered exception. " + ex.Message);
    }
}

Add WebResultsWithCountAndOffset to main:

static void Main(string[] args)
{
    var client = new WebSearchClient(new ApiKeyServiceClientCredentials("YOUR_SUBSCRIPTION_KEY"));

    WebResults(client);
    // Search with count and offset...
    WebResultsWithCountAndOffset(client);  
    // Search with news filter...
    WebSearchWithResponseFilter(client);

    Console.WriteLine("Press any key to exit...");
    Console.ReadKey();
}

Run the application.

Use safe search, answer count, and the promote filter

This sample uses the answer_count, promote, and safe_search parameters to filter search results for "Music Videos". The Name and ContentUrl for the first result are displayed.

Add this code to your console project:

public static async void WebSearchWithAnswerCountPromoteAndSafeSearch(WebSearchClient client)
{
    try
    {
        IList<string> promoteAnswertypeStrings = new List<string>() { "videos" };
        var webData = await client.Web.SearchAsync(query: "Music Videos", answerCount: 2, promote: promoteAnswertypeStrings, safeSearch: SafeSearch.Strict);
        Console.WriteLine("\r\nSearching for \"Music Videos\"");

        if (webData?.Videos?.Value?.Count > 0)
        {
            var firstVideosResult = webData.Videos.Value.FirstOrDefault();

            if (firstVideosResult != null)
            {
                Console.WriteLine("Video Results # {0}", webData.Videos.Value.Count);
                Console.WriteLine("First Video result name: {0} ", firstVideosResult.Name);
                Console.WriteLine("First Video result URL: {0} ", firstVideosResult.ContentUrl);
            }
            else
            {
                Console.WriteLine("Couldn't find videos results!");
            }
        }
        else
        {
            Console.WriteLine("Didn't see any data..");
        }
    }
    catch (Exception ex)
    {
        Console.WriteLine("Encountered exception. " + ex.Message);
    }
}

Add WebResultsWithCountAndOffset to main:

static void Main(string[] args)
{
    var client = new WebSearchClient(new ApiKeyServiceClientCredentials("YOUR_SUBSCRIPTION_KEY"));

    WebResults(client);
    // Search with count and offset...
    WebResultsWithCountAndOffset(client);  
    // Search with news filter...
    WebSearchWithResponseFilter(client);
    // Search with answer count, promote, and safe search
    WebSearchWithAnswerCountPromoteAndSafeSearch(client);

    Console.WriteLine("Press any key to exit...");
    Console.ReadKey();
}

Run the application.

Clean up resources

When you're done with this project, make sure to remove your subscription key from the application's code.

Next steps

Cognitive Services .NET SDK samples

Quickstart: Use a Bing Web Search .NET client library

Prerequisites

Create a project and install dependencies

Declare dependencies

Create project scaffolding

Construct a request

Handle the response

Declare the main method

Run the application

Define functions and filter results

Limit the number of results returned by Bing

Filter for news

Use safe search, answer count, and the promote filter

Clean up resources

Next steps

Commenti e suggerimenti

Risorse aggiuntive