SearchPaneSuggestionsRequestDeferral Class

Definition

Enables the app to signal when it has finished populating a searchSuggestionCollection object while handling the suggestionsrequested event. Apps should use a deferral if and only if they need to respond to a request for suggestions asynchronously.

public ref class SearchPaneSuggestionsRequestDeferral sealed
/// [Windows.Foundation.Metadata.ContractVersion(Windows.ApplicationModel.Search.SearchContract, 65536)]
/// [Windows.Foundation.Metadata.Deprecated("SearchPaneSuggestionsRequestDeferral may be altered or unavailable for releases after Windows 10.", Windows.Foundation.Metadata.DeprecationType.Deprecate, 65536, Windows.ApplicationModel.Search.SearchContract)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
class SearchPaneSuggestionsRequestDeferral sealed
/// [Windows.Foundation.Metadata.ContractVersion(Windows.ApplicationModel.Search.SearchContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Deprecated("SearchPaneSuggestionsRequestDeferral may be altered or unavailable for releases after Windows 10.", Windows.Foundation.Metadata.DeprecationType.Deprecate, 65536, "Windows.ApplicationModel.Search.SearchContract")]
class SearchPaneSuggestionsRequestDeferral sealed
[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.ApplicationModel.Search.SearchContract), 65536)]
[Windows.Foundation.Metadata.Deprecated("SearchPaneSuggestionsRequestDeferral may be altered or unavailable for releases after Windows 10.", Windows.Foundation.Metadata.DeprecationType.Deprecate, 65536, typeof(Windows.ApplicationModel.Search.SearchContract))]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
public sealed class SearchPaneSuggestionsRequestDeferral
[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.ApplicationModel.Search.SearchContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Deprecated("SearchPaneSuggestionsRequestDeferral may be altered or unavailable for releases after Windows 10.", Windows.Foundation.Metadata.DeprecationType.Deprecate, 65536, "Windows.ApplicationModel.Search.SearchContract")]
public sealed class SearchPaneSuggestionsRequestDeferral
Public NotInheritable Class SearchPaneSuggestionsRequestDeferral
Inheritance
SearchPaneSuggestionsRequestDeferral
Attributes

Windows 10 requirements

Device family
Windows Desktop Extension SDK (introduced in 10.0.10240.0)
Xbox One Extensions for the UWP (introduced in 10.0.10586.0)
API contract
Windows.ApplicationModel.Search.SearchContract (introduced in v1.0)

Examples

The Search contract sample demonstrates how to respond to a suggestionsrequested event, including how to get a deferral.

private async void OnSearchPaneSuggestionsRequested(SearchPane sender, SearchPaneSuggestionsRequestedEventArgs e)
{
    var queryText = e.QueryText;
    if (string.IsNullOrEmpty(queryText))
    {
        MainPage.Current.NotifyUser("Use the search pane to submit a query", NotifyType.StatusMessage);
    }
    else if (string.IsNullOrEmpty(UrlTextBox.Text))
    {
        MainPage.Current.NotifyUser("Please enter the web service URL", NotifyType.StatusMessage);
    }
    else
    {
        // The deferral object is used to supply suggestions asynchronously for example when fetching suggestions from a web service.
        var request = e.Request;
        var deferral = request.GetDeferral();

        try
        {
            // Use the web service Url entered in the UrlTextBox that supports XML Search Suggestions in order to see suggestions come from the web service.
            // See http://msdn.microsoft.com/library/cc848863(v=vs.85).aspx for details on XML Search Suggestions format.
            // Replace "{searchTerms}" of the Url with the query string.
            Task task = GetSuggestionsAsync(Regex.Replace(UrlTextBox.Text, "{searchTerms}", Uri.EscapeDataString(queryText)), request.SearchSuggestionCollection);
            await task;
            if (task.Status == TaskStatus.RanToCompletion)
            {
                if (request.SearchSuggestionCollection.Size > 0)
                {
                    MainPage.Current.NotifyUser("Suggestions provided for query: " + queryText, NotifyType.StatusMessage);
                }
                else
                {
                    MainPage.Current.NotifyUser("No suggestions provided for query: " + queryText, NotifyType.StatusMessage);
                }
            }
        }
        catch (TaskCanceledException)
        {
            // Previous suggestion request was canceled.
        }
        catch (FormatException)
        {
            MainPage.Current.NotifyUser("Suggestions could not be retrieved, please verify that the URL points to a valid service (for example http://contoso.com?q={searchTerms})", NotifyType.ErrorMessage);
        }
        catch (Exception)
        {
            MainPage.Current.NotifyUser("Suggestions could not be displayed, please verify that the service provides valid XML Search Suggestions.", NotifyType.ErrorMessage);
        }
        finally
        {
            deferral.Complete();
        }
    }
}

Remarks

Your app should respond asynchronously to a request for suggestions if fulfilling the request will take a significant amount of time, such as fetching suggestions from a web service.

Use the searchPaneSuggestionsRequestDeferral.complete method to signal when your app has fulfilled the request.

An app retrieves this object by calling the searchPaneSuggestionsRequest.getDeferral method while handling the suggestionsrequested event.

Methods

Complete()

Signals that the app has finished populating a searchSuggestionCollection object while handling the suggestionsrequested event.

Applies to

See also