5 out of 12 rated this helpful - Rate this topic

Quickstart: Adding search to an app (Windows Store apps using C#/VB/C++ and XAML)

In this article

Prerequisites
Add search using Visual Studio tools
Complete Search contract integration
Test your Search contract integration
Summary and next steps
Related topics

Important APIs

Let users search your Windows Store app by adding the Search contract. When you add the Search contract, users can search your app from anywhere in their system by selecting the Search charm.

Tip Users can use shortcut keys to access charms, including the Search charm. The Windows Logo Key + C lets the user select any of the charms, and the Windows Logo Key + Q selects the Search charm.

See this feature in action as part of our App features, start to finish series: Windows Store app UI, start to finish

Prerequisites

None.

1. Add search using Visual Studio tools

All Windows Store apps have access to tools in Microsoft Visual Studio Express 2012 for Windows 8. You can use these to successfully add search to your app and adhere to the UX guidelines for search. See Guidelines and checklist for search to learn more.

Open your project in Visual Studio Express 2012 for Windows 8 and follow these steps to use the tools to add search to your app:

Open the Add a New Item dialog.
You can open this dialog several ways:
- By clicking the Project > Add New Item... menu option
- By clicking the Add > New Item... menu option from the project's context menu
- By using the Crtl + Shift + A keyboard shortcut
To add the Search contract from the Add a New Item dialog, select Search Contract from the center pane of the Add a New Item dialog. Then click the Add button.

You can learn more about using Microsoft Visual Studio templates in Templates to speed up your app development.

Here is how the tools help you to fulfill the minimum requirements of the Search contract:

Declare the Search contract in the app manifest.

You can see that the contract was added by clicking on the manifest file in your Visual Studio project and selecting the Declarations tab.
Create a basic search results page for your app.

The search results page, which is created automatically by Visual Studio, adheres to the UX guidelines for results pages in Guidelines and checklist for search.
Respond to a search query while your app is the main app on screen.

When the user searches your app while it is the main app on screen, the system fires a QuerySubmitted event. The Visual Studio tools (globally) register a handler that responds whenever this event fires. The handler then shows your app's search results page for the user's query.
Respond to a search query when your app is not the main app on screen.

When the user searches your app while it is not the main app on screen, the system fires an Activated event and stores the arguments for this event by using SearchActivatedEventArgs. The Visual Studio tools add code to override the OnSearchActivated method. Your app can then respond to this event by showing its search results page for the user's query. This code is added in the App.xaml.cs file.

You can learn more about activating your app in How to activate an app.

2. Complete Search contract integration

Visual Studio added a basic search results page and fulfilled the minimum requirements of the Search contract automatically. However, you still need to take the following steps to ensure that your app is completely integrated, and that your users will have a positive experience when they search your app.

Add filters to your page

By default no filters are shown on your search results page. You should add filters that make sense for your app and users, by adding code to the LoadState method. The method is commented to help make implementation easier.
Populate your page with results from your app's data

To use the query text and current filter to populate your page with results, you should add code to the Filter_SelectionChanged method in the search result page code (SearchResultsPage.xaml.cs by default). You can access the query text from the DefaultViewModel object. This is where the LoadState method stores query text (in quotes) by default. The Filter_SelectionChanged is commented to help make implementation easier.
Handle activation for empty search queries

Users may select your app from the Search charm without entering query text. They may do this to scope their search to your app, or simply as a quick way to get back to what they were last looking at. Your app should anticipate the user's needs and respond differently in each case.

Add code to your app's search-activated event handler that checks the QueryText. This handler was added automatically by Visual Studio. Then, to help determine which app page is best to display when your app is activated and QueryText is empty, use the following logic:
- When your app is launched for the first time, display your app's home page.
- If your app is suspended or running in the background, display your app's current page.
- Otherwise, display a generic search landing page.
Add search suggestions

Search suggestions are displayed under the search box in the search pane. Suggestions are important because they save users' time and give valuable hints about the kinds of things users can search for in your app.

You can get suggestions from several sources:
- You can define them yourself. For example, you could create a list of car manufacturers.
- You can get them from Windows if your app searches local files.
- You can get them from a web service or server.
For user experience guidelines about displaying suggestions in the search pane, see Guidelines and checklist for search.

You can use LocalContentSuggestionSettings to add suggestions, based on local files from Windows, in only a few lines of code. Alternatively, you can register for the SuggestionsRequested event and build your own list of suggestions that is made up of suggestions you retrieved from another source (like a locally-defined list or a web service).

For code examples that show how to add search suggestions, download the Search contract sample. The sample demonstrates how to add search suggestions by using all three possible sources, and how to add suggestions for East Asian languages by using an Input Method Editor (IME).
Enable users to type into the search box directly from your app

You should give your users the ability to search for content in your app by simply beginning to type with their keyboard.

Many people will use a keyboard to interact with Windows 8. Letting users search by typing makes efficient use of keyboard interaction and makes your app's search experience consistent with the Start screen.

Use SearchPane.ShowOnKeyboardInput so that the search box receives input when a user types. Enable ShowOnKeyboardInput on your app's main page and on search results pages, so that users can search your app quickly and consistently. For user experience guidelines about using typing to search in your app, see Guidelines and checklist for search.
If needed, customize the look of search results

The search results page defines an item template that displays a small image, with adjacent title and properties, for each result. By default, the template and associated styles are defined in Common/StandardStyles.xaml.

If the default item template doesn't suit your search results, you should update it by copying the item template locally, and then modify it. You can learn more about ListView and GridView item templates in Item templates for grid layouts and Item templates for list layouts.
If needed, add navigation to a result's details page

If you want to display detailed information about a result that the user selected, you should create an app page specifically to display this information and navigate to that page when a result is selected. You should register an event handler for the ItemClick event on both ListView and GridView (you can use a single handler). Then your app can navigate to the result detail page when it is the main app on screen and when it is snapped.

You can learn more about page navigation in Quickstart: Navigating between pages.

3. Test your Search contract integration

You should test your app's integration with the Search contract by using the Search charm to search your app in each of the following circumstances. Use at least these two test queries in each case:

A query with search term(s) that you know should have search results
An empty query

Perform test searches while your app is the main app on screen. Launch your app, open the Search charm while that app is active, and enter each query.
Perform test searches when your app is not the main app on screen. Launch your app, switch to the start screen, and then open the Search charm and enter each query.
Perform test searches while your app is snapped. Launch your app and snap it, make sure your app stays on its home page, and then open the Search charm and enter each query.
Perform test searches when your app is launched for the first time. Make sure your app is not running and is not suspended before you open the Search charm and enter each query.

Summary and next steps

You used the tools built into Visual Studio Express 2012 for Windows 8 to add search to your app. Now, users should be able to use the Search charm to search your app.

If you’d like to try working with the Search charm and other key Windows 8 features, you can also download the hands-on labs for Windows 8. These labs provide a modular, step-by-step introduction to creating a sample Windows Store app in the programming language of your choice (JavaScript and HTML or C# and XAML).