Published: 15 Sep 2008
By: Scott Mitchell

Scott Mitchell shows how to implement searching with Google Custom Search in ASP.NET.

Contents [hide]


ASP.NET's site map feature and SiteMapPath, TreeView, and Menu controls help visitors navigate your site and find the information they are looking for. However, ASP.NET does not provide any built-in functionality for search, which is the most common way people find information online. This is unfortunate because it gives ASP.NET developers the impression that search is not essential, but that couldn't be farther from the truth. Companies like Google and Yahoo! have made search part of the de facto website user interface. Web giants like,,, and all share one thing in common - a prominent search bar at the top of each and every page. People expect a search box on a website as much as they expect a close icon in the upper right corner of their windows.

Implementing a search engine is no easy task. It involves creating and maintaining an index and indexing content that may reside in a variety of locations (in a database or on the file system) and in a variety of formats (text, PDF, Microsoft Word documents, and so on). And implementing a general purpose search engine that works across different configurations is even more complex, so I understand why Microsoft omitted a Search control from the Toolbox.

A simpler alternative is to use Google's Custom Search Engine (CSE). Normally, when you search Google the results are pulled from their master index that includes millions of websites. With the CSE you can constrain the search results to a specified set of websites. What's more, you can add a CSE search box to your site and have the results displayed on a page in your site.

There is no such thing as a free lunch, and Google's CSE is no exception. The search results displayed on your site include a handful of text ads at right, top and right, or top and bottom of the search results. (Non-profits, universities, and government agencies may omit these ads.) The good news is that you can associate your CSE account with a Google AdSense account and make money when users click the ads shown in the CSE results. Another option is to use SiteSearch, which is Google's ad-free version of its CSE. Pricing starts at $100 per year and goes up from there depending on the number of pages indexed and the number of searches performed.

This article provides step-by-step instructions on how to use Google's CSE to implement search on an ASP.NET website. In particular, it shows the steps I took to add search to my blog, ScottOnWriting.NET.

Getting Started with the Google Custom Search Engine

Start by visiting the Google's Custom Search Engine homepage and clicking the "Create a Custom Search Engine" button. This takes you to a one-page form that prompts you for the name of your custom search engine, a description, and sites to include in your search. You can configure the CSE to search just particular URLs, parts of sites, entire sites, or entire domains. For example, to search just .aspx pages in your site enter*.aspx in the Sites to Search textbox. Because I want to search all pages on my blog (http://www.ScottOnWriting.NET/sowBlog/) I entered the string*.

Figure 1: Specify the sites to include in your CSE results.

Specify the sites 

to include in your CSE results.

Once you've entered the sites to search and answered the other questions on this form, click Next. This takes you to a page where you can test out your custom search engine by entering queries and viewing the results. From the test page click the Finish button to create the custom search engine.

When testing your custom search engine you may not get back the results you expect. Keep in mind that the search results returned by CSE are a subset of those found in Google's master index. Therefore, there will be a delay between when you add a new page to your site and when it appears in the CSE. Moreover, any pages that are not available to anonymous users, or are otherwise omitted from search engines due to a Robots.txt file or other factors, will not be included in the results.

Adding a Custom Search Engine to Your Website

After creating your custom search engine you are taken to the My Search Engines page. From here you can manage your custom search engines and view usage statistics.

Figure 2: Manage your custom search engines and view usage statistics from this page.

Manage your custom search engines and view usage statistics from this page.

Click the "control panel" link. This takes you to a multi-tabbed page where you can edit your custom search engine's basic information, change what sites are included in the results, see how many pages are included in the index, and add refinements to help users narrow their search results.

The control panel's Code tab provides the HTML and JavaScript you need to embed in your site in order to show the CSE search box. You can configure the results to be shown on Google's website or to host them on your own site. As the screenshot below shows, there are two options for hosting the results on your website:

  • Showing them in an <iframe>
  • Showing the results in an overlay

The <iframe> option provides users with the typical search experience: they enter their query in a search box and, on submission, are taken to a different page and shown the results. Consequently, this approach requires that you create a web page on your site to display the search results. Because the results are loaded using an <iframe> that gets its content from a remote server (namely, Google's), no server-side code is needed to display these results. Therefore, the search results page can be implemented as an ASP.NET page (.aspx) or an HTML (.htm) page.

The overlay option displays the search results on the same page from where the search was performed, laying the results over the current page's content using a modal HTML element. You cannot make any AdSense income from the ads in the search results shown in the overlay. Furthermore, to use the overlay option you must first sign up to use Google's free AJAX Search API.

I decided to use the <iframe> option for my blog because it implements the search experience users are most accustomed to.

Figure 3: Generate the markup and script to display the search box and results in your website.

Generate the markup and script to display the search box and results in your website.

The search box and search results markup are displayed in textboxes on the Code tab. Note that if you select the <iframe> option (as I did in the screenshot above) then you need to also provide the URL to the search results page on your site. I created a new HTML page named SearchResults.htm to display the results.

Copy the markup for the search box and paste it into your website wherever you want the search box to appear. I recommend adding it to your master page so that the search box appears on every page in your site. Next, open the page you created to display the results and add the markup for the search results.

That's all there is to it!

It's easy to customize the appearance of the search box and search results. You can choose among different search box displays and adjust the search results colors from the "Look and feel" tab.

The following screenshot shows the search box on my blog.

Figure 4: A search box is displayed at the top of every page on my blog.


search box is displayed at the top of every page on my blog.

Entering a query into the search box and clicking "Search" sends the user to the results page.

Figure 5: A search box is displayed at the top of every page on my blog.


search box is displayed at the top of every page on my blog.

Embedding the Search Box in an ASP.NET Page with a Postback Form

One challenge with adding the Google CSE to an ASP.NET website is that the search box markup is implemented as a form. The search box markup suggested by Google for my blog follows:

Most ASP.NET pages already have a postback form present, which complicates integrating the search box form into your ASP.NET pages. In my first attempt at adding the search box I stripped off the <form> tags from Google's suggested markup, placing the <input> elements within the page's existing postback form:

This displays the search box, but clicking the Search button triggers a postback. That won't do.

Because the <form> uses the action="get" behavior it sends its form fields through the querystring. Therefore, we can view the search results by visiting the URL directly. For example, to see the search results for the term "ASP.NET" visit:

To take advantage of this fact I updated the suggested search box markup to contain just two <input> elements: one for the query text and a Search button. Next, I added a client-side onclick event handler to call a JavaScript function that redirects the user to the search results URL.

The SearchSite function is shown below:

An alternative approach, which would work just as well, would be to replace the <input> tags with TextBox and Button Web controls. Next, you could create a server-side Click event handler that used a Response.Redirect to send the user to the search results page. The JavaScript approach, while a bit more cumbersome, saves a trip to the web server.

This is a good first stab at the problem but suffers from two problems. First, the search term is copied into the search results page URL directly. Consider what would happen if the user entered a search term with an ampersand (&), such as Scott&Jisun. It would results in a querystring like SearchResults.htm?...&q=Scott&Jisun&sa=.... As you can see, the CSE would think the search term was just Scott. The text after the ampersand (Jisun) is assumed to be a separate querystring field. To remedy this faulty behavior we need to escape the user's search query. ASP.NET includes the handy Server.UrlEncode method, but that's a server-side method. A bit of searching turned up a JavaScript equivalent: JavaScript URL encoding and decoding.

The second problem is that the JavaScript that redirects the user to the search page only executes when the Search button is clicked. If the user types in the search query and hits enter the postback form is submitted. To fix this I created a client-side onkeypress event handler for the search box. If the Enter key is pressed while the focus is in the search box the SearchSite function is called.

The complete markup and script for these enhancements follows:

Listing 1: Search Box Markup to Appear within the Postback Form

Listing 2: The Relevant JavaScript


Every website with more than a few web pages should have a site search engine. Your visitors expect to be able to search your site and search is the first thing they'll try when they are at your site but can't find what they're looking for. A quick way to add search to your site is to use Google's Custom Search Engine tool, which allows you to search against Google's master index but pare down the results to only those found in a select set of websites. The CSE search box and results can be embedded within your website, providing your visitors with a fully functional site-wide search experience.

Happy Programming!


<<  Previous Article Continue reading and see our next or previous articles Next Article >>

About Scott Mitchell

Scott Mitchell, author of eight ASP/ASP.NET books and founder of, has been working with Microsoft Web technologies since 1998. Scott works as an independent consultant, trainer, ...

This author has published 16 articles on DotNetSlackers. View other articles or the complete profile here.

Other articles in this category

Code First Approach using Entity Framework 4.1, Inversion of Control, Unity Framework, Repository and Unit of Work Patterns, and MVC3 Razor View
A detailed introduction about the code first approach using Entity Framework 4.1, Inversion of Contr...
Exception Handling and .Net (A practical approach)
Error Handling has always been crucial for an application in a number of ways. It may affect the exe...
jQuery Mobile ListView
In this article, we're going to look at what JQuery Mobile uses to represent lists, and how capable ...
Book Review: SignalR: Real-time Application Development
A book review of SignalR by Simone.
JQuery Mobile Widgets Overview
An overview of widgets in jQuery Mobile.

You might also be interested in the following related blog posts

Designer Support for One-Way navigations in Entity Framework 4 read more
How to fix Sys.WebForms.PageRequestManagerParserErrorException in ASP.NET 2.0 AJAX 1.0 read more
How To: Silverlight grid hierarchy load on demand using MVVM and RIA services read more
Free software for you! WebsiteSpark let the mountain go to Microsoft instead. read more
Customizing the SharePoint ECB with Javascript, Part 3 read more
Why VBA Still Makes Sense read more
Dissecting storage: Documents and Fields read more
Customizing the SharePoint ECB with Javascript, Part 1 read more
WebAii Testing Framework: From HTML to XAML and Back -- RadHtmlPlaceholder read more
Ruminations on Multi-Tenant Data Architectures read more


Subject Author Date
placeholder Issue with Google Analytics tracking Ven Golfer 5/14/2009 5:06 PM
Can this code be extended to non-European languages? Melinda Hull 1/11/2010 8:55 AM
placeholder Can use iFrame method also to put google search on master page Anil Gupta 5/27/2010 10:31 AM
Great as always, a life-saver! Erik Bertrand 11/5/2008 7:28 PM
placeholder Thanks for a Great Solution Brian McNamara 11/7/2008 6:21 PM
Excellent stuff - just one small addition... Stuart Lodge 11/26/2008 12:33 PM
placeholder Do you have a server-side + client-side solution? Jeff M. 12/4/2008 7:09 PM
Improved version!!! Jeff M. 1/22/2009 12:24 AM
placeholder Won't keep focus with form or Flash on page with enter key? Joe King 2/24/2009 6:38 PM
Can it be tested while development Gemini Gemini 3/16/2009 5:46 AM
placeholder RE: Can it be tested while development Scott Mitchell 5/14/2009 5:14 PM

Please login to rate or to leave a comment.