Implementing the Search Contract in Windows Store Apps

 Apr 02, 2015

Windows 8 introduced the concept of contracts. You can think of a contract as an agreement between the app and the operating system (OS). There are a fair number of contracts, as for example the Share contract, the Search contract, the Play-to contract and a few others.

The idea is that once an app implements a contract, it can interact with the OS and with other apps in a standard way. Let's say your app is some kind of content provider and you want to make searching from your app content always available. Without this idea of a contract, you would need to know beforehand which other apps would want to search from your app and have all those apps call some private API to launch your app and start the search. If your app implements the search contract, all it takes is to display the charms bar by swiping from the right or pointing your mouse to the top right or bottom left corners of the window and then clicking the Share charm. Your can then type some search keyword and pick your app as the one where the search will be executed. The results will be a list of pages from your app and you can just select one of those and start reading the content. You don't need to explicitly launch your app or close the app you were using before.

Let's see the details of implementing the Search Contract in a Windows Store App.

First step is to declare the support for the Search contract in the app package manifest. Double-click Package.appxmanifest in the Solution Explorer and open the Declarations tab. On Available Declarations, select Search and click Add.

Now, you add a Search Results Page to your project. For that, just right-click the project root node in Solution Explorer, select Add | New Item.. and pick the template Search Results Page. You can give any name to that page. In this case, I will call it the ResultsSearchPage. This is the page that will show up after you fill in the search box in the Search charm and click your app in the list of apps that support Search.

Now we need to write some code to display the Results Search Page when a query is submitted to your app through the Search charm. We need to register an event handler for the QuerySubmitted event. In App.xaml.cs, add the following:

protected override async void OnWindowCreated(WindowCreatedEventArgs args){ await CoreApplication.MainView.CoreWindow.Dispatcher.RunAsync (CoreDispatcherPriority.Normal, async () => { SearchPane.GetForCurrentView().QuerySubmitted += OnQuerySubmitted; }); }
The use of the RunAsync method above is to force the code to run on the main thread. Apart from that small complication, all we have done is add OnQuerySubmitted as the handler for the QuerySubmitted event. Now comes the code that will respond to the query:
private void OnQuerySubmitted(object sender, SearchPaneQuerySubmittedEventArgs args){ Frame frame1 = Windows.Current.Content == null ? new Frame() : Window.Current.Content as Frame; frame1.Navigate(typeof(SearchResultsPage), args.QueryText); }
All we've done here was to make sure we have an instance of a Frame and then use the Navigate method of the Frame to go to the SearchResultPage passing the QueryText to that page.

The LoadState event of SearchResultsPage can retrieve the QueryText through its navigation parameter and we can write the logic to get the list of pages that satisfy the query and populate the ListView in that page with the query results. Usually, this would be done by binding the ListView with a collection defined in the ViewModel used by the page and then we just populate that collection with the query results.

There is a lot more to learn about Search Contracts. If you want to find out more, I recommend you take a look into New Horizons' 20484: Essentials of Developing Windows Store Apps Using C# training course.

How do your Excel skills stack up?   

Test Now  

About the Author:

Newton Godoy  

With over 17 years of in-class training experience and over 16 years of industry experience, Newton offers students a wealth of real-world technical knowledge and expertise in the areas of .NET application development, SQL Server and SharePoint Server. After spending several years lecturing as a professor, Newton found his true calling and began his career as a MCT. He worked as a technical trainer for some of Brazil's and Australia’s largest corporate training organisations before finally finding a home with New Horizons where he is now one of our top trainers. Newton brings a thorough mentoring capability to the classroom where he can advise on technical issues and challenges often beyond the scope of the course curriculum. His combination of technical knowledge and instructor experience make him one of the most respected instructors within the IT training industry.

Read full bio
Back to top