Build a console app search client in C#
This tutorial shows how to build a simple .NET Core console app that allows users to query the Bing Web Search API and display ranked results.
This tutorial shows how to:
- Make a simple query to the Bing Web Search API.
- Display query results in ranked order.
Prerequisites
To follow along with the tutorial, you need:
- An Azure subscription - Create one for free.
- Once you have your Azure subscription, create a Bing Search resource in the Azure portal to get your key and endpoint. After it deploys, click Go to resource.
- The Visual Studio IDE.
Create a new Console App project
In Visual Studio, create a project with Ctrl
+Shift
+N
.
In the New Project dialog, click Visual C# > Windows Classic Desktop > Console App (.NET Framework).
Name the application MyConsoleSearchApp, and then click OK.
Add the JSON.net NuGet package to the project
JSON.net allows you to work with the JSON responses returned by the API. Add its NuGet package to your project:
- In Solution Explorer, right-click on the project and select Manage NuGet Packages.
- On the Browse tab, search for
Newtonsoft.Json
. Select the latest version, and then click Install. - Click the OK button on the Review Changes window.
- Close the Visual Studio tab titled NuGet: MyConsoleSearchApp.
Add a reference to System.Web
This tutorial relies on the System.Web
assembly. Add a reference to this assembly to your project:
- In Solution Explorer, right-click on References and select Add Reference
- Select Assemblies > Framework, then scroll down and check System.Web.
- Select OK.
Add some necessary using statements
The code in this tutorial requires three additional using statements. Add these statements below the existing using
statements at the top of Program.cs:
using System.Web;
using System.Net.Http;
Ask the user for a query
In Solution Explorer, open Program.cs. Update the Main()
method:
static void Main()
{
// Get the user's query
Console.Write("Enter Bing query: ");
string userQuery = Console.ReadLine();
Console.WriteLine();
// Run the query and display the results
RunQueryAndDisplayResults(userQuery);
// Prevent the console window from closing immediately
Console.WriteLine("\nHit ENTER to exit...");
Console.ReadLine();
}
This method:
- Asks the user for a query.
- Calls
RunQueryAndDisplayResults(userQuery)
to execute the query and display the results. - Waits for user input in order to prevent the console window from immediately closing.
Search for query results using the Bing Web Search API
Next, add a method that queries the API and displays the results:
static void RunQueryAndDisplayResults(string userQuery)
{
try
{
// Create a query
var client = new HttpClient();
client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "<YOUR_SUBSCRIPTION_KEY_GOES_HERE>");
var queryString = HttpUtility.ParseQueryString(string.Empty);
queryString["q"] = userQuery;
var query = "https://api.bing.microsoft.com/v7.0/search?" + queryString;
// Run the query
HttpResponseMessage httpResponseMessage = client.GetAsync(query).Result;
// Deserialize the response content
var responseContentString = httpResponseMessage.Content.ReadAsStringAsync().Result;
Newtonsoft.Json.Linq.JObject responseObjects = Newtonsoft.Json.Linq.JObject.Parse(responseContentString);
// Handle success and error codes
if (httpResponseMessage.IsSuccessStatusCode)
{
DisplayAllRankedResults(responseObjects);
}
else
{
Console.WriteLine($"HTTP error status code: {httpResponseMessage.StatusCode.ToString()}");
}
}
catch (Exception e)
{
Console.WriteLine(e.Message);
}
}
This method:
- Creates an
HttpClient
to query the Web Search API. - Sets the
Ocp-Apim-Subscription-Key
HTTP header, which Bing uses to authenticate the request. - Executes the request and uses JSON.net to deserialize the results.
- Calls
DisplayAllRankedResults(responseObjects)
to display all results in ranked order.
Make sure to set the value of Ocp-Apim-Subscription-Key
to your subscription key.
Display ranked results
Before showing how to display the results in ranked order, take a look at a sample web search response:
{
"_type" : "SearchResponse",
"webPages" : {
"webSearchUrl" : "https:\/\/www.bing.com\/cr?IG=70BE289346...",
"totalEstimatedMatches" : 982000,
"value" : [{
"id" : "https:\/\/api.cognitive.microsoft.com\/api\/v7\/#WebPages.0",
"name" : "Contoso Sailing Club - Seattle",
"url" : "https:\/\/www.bing.com\/cr?IG=70BE289346ED4594874FE...",
"displayUrl" : "https:\/\/contososailingsea...",
"snippet" : "Come sail with Contoso in Seattle...",
"dateLastCrawled" : "2017-04-07T02:25:00"
},
{
"id" : "https:\/\/api.cognitive.microsoft.com\/api\/7\/#WebPages.6",
"name" : "Contoso Sailing Lessons - Official Site",
"url" : "http:\/\/www.bing.com\/cr?IG=70BE289346ED4594874FE...",
"displayUrl" : "https:\/\/www.constososailinglessonsseat...",
"snippet" : "Contoso sailing lessons in Seattle...",
"dateLastCrawled" : "2017-04-09T14:30:00"
},
...
],
"someResultsRemoved" : true
},
"relatedSearches" : {
"id" : "https:\/\/api.cognitive.microsoft.com\/api\/7\/#RelatedSearches",
"value" : [{
"text" : "sailing lessons",
"displayText" : "sailing lessons",
"webSearchUrl" : "https:\/\/www.bing.com\/cr?IG=70BE289346E..."
}
...
]
},
"rankingResponse" : {
"mainline" : {
"items" : [{
"answerType" : "WebPages",
"resultIndex" : 0,
"value" : {
"id" : "https:\/\/api.cognitive.microsoft.com\/api\/v7\/#WebPages.0"
}
},
{
"answerType" : "WebPages",
"resultIndex" : 1,
"value" : {
"id" : "https:\/\/api.cognitive.microsoft.com\/api\/v7\/#WebPages.1"
}
}
...
]
},
"sidebar" : {
"items" : [{
"answerType" : "RelatedSearches",
"value" : {
"id" : "https:\/\/api.cognitive.microsoft.com\/api\/v7\/#RelatedSearches"
}
}]
}
}
}
The rankingResponse describes the appropriate display order for search results. It includes one or more of the following, prioritized groups:
pole
: The search results to get the most visible treatment (for example, displayed above the mainline and sidebar).mainline
: The search results to display in the mainline.sidebar
: The search results to display in the sidebar. If there is no sidebar, display the results below the mainline.
The ranking response JSON may include one or more of the groups.
In Program.cs, add the following method to display results in properly ranked order:
static void DisplayAllRankedResults(Newtonsoft.Json.Linq.JObject responseObjects)
{
string[] rankingGroups = new string[] { "pole", "mainline", "sidebar" };
// Loop through the ranking groups in priority order
foreach (string rankingName in rankingGroups)
{
Newtonsoft.Json.Linq.JToken rankingResponseItems = responseObjects.SelectToken($"rankingResponse.{rankingName}.items");
if (rankingResponseItems != null)
{
foreach (Newtonsoft.Json.Linq.JObject rankingResponseItem in rankingResponseItems)
{
Newtonsoft.Json.Linq.JToken resultIndex;
rankingResponseItem.TryGetValue("resultIndex", out resultIndex);
var answerType = rankingResponseItem.Value<string>("answerType");
switch (answerType)
{
case "WebPages":
DisplaySpecificResults(resultIndex, responseObjects.SelectToken("webPages.value"), "WebPage", "name", "url", "displayUrl", "snippet");
break;
case "News":
DisplaySpecificResults(resultIndex, responseObjects.SelectToken("news.value"), "News", "name", "url", "description");
break;
case "Images":
DisplaySpecificResults(resultIndex, responseObjects.SelectToken("images.value"), "Image", "thumbnailUrl");
break;
case "Videos":
DisplaySpecificResults(resultIndex, responseObjects.SelectToken("videos.value"), "Video", "embedHtml");
break;
case "RelatedSearches":
DisplaySpecificResults(resultIndex, responseObjects.SelectToken("relatedSearches.value"), "RelatedSearch", "displayText", "webSearchUrl");
break;
}
}
}
}
}
This method:
- Loops over the
rankingResponse
groups that the response contains. - Displays the items in each group by calling
DisplaySpecificResults(...)
.
In Program.cs, add the following two methods:
static void DisplaySpecificResults(Newtonsoft.Json.Linq.JToken resultIndex, Newtonsoft.Json.Linq.JToken items, string title, params string[] fields)
{
if (resultIndex == null)
{
foreach (Newtonsoft.Json.Linq.JToken item in items)
{
DisplayItem(item, title, fields);
}
}
else
{
DisplayItem(items.ElementAt((int)resultIndex), title, fields);
}
}
static void DisplayItem(Newtonsoft.Json.Linq.JToken item, string title, string[] fields)
{
Console.WriteLine($"{title}: ");
foreach( string field in fields )
{
Console.WriteLine($"- {field}: {item[field]}");
}
Console.WriteLine();
}
These methods work together to output the search results to the console.
Run the application
Run the application. The output should look similar to the following:
Enter Bing query: sailing lessons seattle
WebPage:
- name: Contoso Sailing Club - Seattle
- url: https://www.bing.com/cr?IG=70BE289346ED4594874FE...
- displayUrl: https://contososailingsea....
- snippet: Come sail with Contoso in Seattle...
WebPage:
- name: Contoso Sailing Lessons Seattle - Official Site
- url: http://www.bing.com/cr?IG=70BE289346ED4594874FE...
- displayUrl: https://www.constososailinglessonsseat...
- snippet: Contoso sailing lessons in Seattle...
...
Next steps
Read more about using ranking to display results.
Feedback
https://aka.ms/ContentUserFeedback.
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see:Submit and view feedback for