OpenSearch Client Library for .NET - Walkthrough

The OpenSearch Client Library for .NET is a .NET class library designed to significantly speed-up integration with OpenSearch sources.

This walkthrough describes the main steps involved in using the client library to query an OpenSearch data-source.

Referencing the Client Library DLL

To get started using the Client Library, add a reference to the library (Clarience.OpenSearch.Client.dll), installed by default in: %ProgramFiles%\Clarience\OpenSearch Client Library for .NET

Right-click on your Visual Studio project and select Add reference... Browse to the folder where you installed the Client Library DLL, select the DLL and click OK.

The code examples that follow assume that an appropriate using directive / Imports statement is present:

    using Clarience.OpenSearch.Client;
    

    Imports Clarience.OpenSearch.Client
    

Note: The OpenSearch Client Library references System.ServiceModel.Web. This is not included in the .NET Framework 4 Client Profile. If your project is targeting .NET 4.0 you must set the target framework to ".NET Framework 4" under Project Properties.

Providing an OpenSearch Description

The first step in querying any OpenSearch data-source is to create an OpenSearchDescription object that represents an OpenSearch Description. The OpenSearch Description provides details about a particular OpenSearch data-source that you plan to interact with.

At a minimum and in order to be useful as a target for OpenSearch queries, the OpenSearchDescription object must have at least one OpenSearchUrlTemplate specified.

An example is shown here:

    var openSearchUrlTemplate = new OpenSearchUrlTemplate()
    {
        UrlTemplate = "http://api.bing.com/rss.aspx?source=web&query={searchTerms}&web.count={count}"
    };

    var openSearchDescription = new OpenSearchDescription(openSearchUrlTemplate);
    

    Dim openSearchUrlTemplate As New OpenSearchUrlTemplate

    openSearchUrlTemplate.UrlTemplate = "http://api.bing.com/rss.aspx?source=web&query={searchTerms}&web.count={count}"

    Dim openSearchDescription As New OpenSearchDescription(openSearchUrlTemplate)
    

Constructing a search query

An OpenSearchQuery object represents the parameters of your search query, for example, the search terms and desired number of results. An example is shown here:

    var openSearchQuery = new OpenSearchQuery()
    {
        SearchTerms = "search keywords",
        Count = 10
    };
    

    Dim openSearchQuery As New OpenSearchQuery
    With openSearchQuery
        .SearchTerms = "search keywords"
        .Count = 10
    End With
    

Performing the search

The OpenSearchGateway class provides methods to query the target OpenSearch data-source. In this example, the Execute method is called, passing the OpenSearchQuery object created earlier.

    var openSearchGateway = new OpenSearchGateway(openSearchDescription, openSearchUrlTemplate);

    var openSearchResult = openSearchGateway.Execute(openSearchQuery);
    

    Dim openSearchGateway As New OpenSearchGateway(openSearchDescription, openSearchUrlTemplate)

    Dim openSearchResult As IOpenSearchResult = openSearchGateway.Execute(openSearchQuery)
    

Processing the results

Results are represented by an IOpenSearchResult interface.

The following code snippet demonstrates how to iterate through each item in a result-set.

    foreach (var openSearchResultItem in openSearchResult.Items)
    {
        // use openSearchResultItem.Title, openSearchResultItem.Summary, etc. here
    }
    

    For Each openSearchResultItem As IOpenSearchResultItem In openSearchResult.Items
        ' use openSearchResultItem.Title, openSearchResultItem.Summary, etc. here
    Next