QueryOptions Class

Definition

Namespace:

Windows.Storage.Search

Specifies the parameters of a search query for enumerating the contents of storage folders.

public ref class QueryOptions sealed

/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Activatable(65536, "Windows.Foundation.UniversalApiContract")]
/// [Windows.Foundation.Metadata.Activatable(Windows.Storage.Search.IQueryOptionsFactory, 65536, "Windows.Foundation.UniversalApiContract")]
class QueryOptions final

[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Activatable(65536, "Windows.Foundation.UniversalApiContract")]
[Windows.Foundation.Metadata.Activatable(typeof(Windows.Storage.Search.IQueryOptionsFactory), 65536, "Windows.Foundation.UniversalApiContract")]
public sealed class QueryOptions

function QueryOptions(query, fileTypeFilter)

Public NotInheritable Class QueryOptions

Inheritance

Object Platform::Object IInspectable QueryOptions

Attributes

ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute

Windows requirements

Device family	Windows 10 (introduced in 10.0.10240.0)
API contract	Windows.Foundation.UniversalApiContract (introduced in v1.0)

Examples

This example demonstrates how to use QueryOptions to query files in a location.

// Set query options with filter and sort order for results
List<string> fileTypeFilter = new List<string>();
fileTypeFilter.Add(".jpg");
fileTypeFilter.Add(".png");
fileTypeFilter.Add(".bmp");
fileTypeFilter.Add(".gif");
var queryOptions = new QueryOptions(CommonFileQuery.OrderByName, fileTypeFilter);

// Create query and retrieve files
var query = KnownFolders.PicturesLibrary.CreateFileQueryWithOptions(queryOptions);
IReadOnlyList<StorageFile> fileList = await query.GetFilesAsync();
// Process results
foreach (StorageFile file in fileList)
{
    // Process file
}

This example demonstrates how to use a file query that is backed by the system index to retrieve properties that may rely on another app's property handler (like Title document property).

try
{
    // Create index backed file query and get results
    List<string> fileTypeFilter = new List<string>();
    fileTypeFilter.Add(".png");
    QueryOptions queryOptions = new QueryOptions(Windows.Storage.Search.CommonFileQuery.OrderByName, fileTypeFilter);
    queryOptions.IndexerOption = IndexerOption.OnlyUseIndexer;
    StorageFileQueryResult queryResult = Windows.Storage.KnownFolders.PicturesLibrary.CreateFileQueryWithOptions(queryOptions);
    var files = await queryResult.GetFilesAsync();

    // Process resulting files
    if (files.Count == 0)
    {
        // Perform tasks to handle no files found
    }
    else
    {
        // Access properties for each file
        foreach (StorageFile file in files)
        {
            var documentProperties = await file.Properties.GetDocumentPropertiesAsync();
            // Perform tasks with document properties
            String title = documentProperties.Title;
        }
    }
}
// Handle errors with catch blocks
catch (FileNotFoundException)
{
 // For example, handle a file not found error
}

Remarks

You can create a file query for any folder you have access to and that you can get as a StorageFolder.

You can use QueryOptions and CreateFileQueryWithOptions to create an indexed backed file query that lets you get properties that rely on another app's property handler.

Constructors

QueryOptions()	Creates an instance of the QueryOptions class for enumerating storage items, and initializes it with the following default settings: QueryOptions.FolderDepth gets FolderDepth.Shallow and QueryOptions.IndexerOption gets IndexerOption.DoNotUseIndexer. A QueryOptions object with the preceding options will provide shallow, folder-by-folder enumeration of the files and folders in a location. By default, folders are enumerated before files and both files and folders are alphabetized by name.
QueryOptions(CommonFileQuery, IIterable<String>)	Creates an instance of the QueryOptions class for enumerating files and initializes it with values provided by the specified CommonFileQuery and an optional file type filter that determines which files to include in query results.
QueryOptions(CommonFolderQuery)	Creates an instance of the QueryOptions class for enumerating subfolders and initializes it with values based on the specified CommonFolderQuery.

Properties

ApplicationSearchFilter	Gets or sets an application-defined Advanced Query Syntax (AQS) string for filtering files by keywords or properties. This property is combined with the UserSearchFilter to create the query's search filter.
DateStackOption	Gets the unit of time used to group files into folders if the QueryOptions object was created with a CommonFolderQuery based on date. For example, if CommonFolderQuery.GroupByYear is used to create a QueryOptions object, the value of this property is DateStackOption.Year.
FileTypeFilter	Gets a list of file name extensions used to filter the search results. If the list is empty, the results include all file types.
FolderDepth	Indicates whether the search query should produce a shallow view of the folder contents or a deep recursive view of all files and subfolder.
GroupPropertyName	Gets the name of the property used to group query results if the QueryOptions object was created using a CommonFolderQuery. For example, if CommonFolderQuery.GroupByYear is used to create a QueryOptions object, the value of this property is System.ItemDate.
IndexerOption	Gets or sets a value that specifies whether the system index or the file system is used to retrieve query results. The indexer can retrieve results faster but is not available in all file locations.
Language	Gets or sets the Internet Engineering Task Force (IETF) language tag (BCP47 standard) that identifies the language associated with the query. This determines the language-specific algorithm used by the system to break the query into individual search tokens.
SortOrder	Gets the list of SortEntry structures that specify how to sort content (like files and subfolders) in query results. Use this list to customize how query results are sorted.
StorageProviderIdFilter	Gets the filter for storage provider identifiers.
UserSearchFilter	Gets or sets a user-defined Advanced Query Syntax (AQS) string for filtering files by keywords or properties. This property is combined with the ApplicationSearchFilter to create the query's search filter.

Methods

LoadFromString(String)	Initializes the current instance of the QueryOptions class with search parameters specified by a string that was created by the SaveToString method.
SaveToString()	Converts the values of a QueryOptions object to a string that can be used to initialize the values of a QueryOptions object by calling LoadFromString.
SetPropertyPrefetch(PropertyPrefetchOptions, IIterable<String>)	Specifies properties that the system should load in advance for all items in the query result set while the query is being executed (instead of retrieving them on a case-by-case basis). If many properties are specified, the query might take longer to execute, but subsequent property retrieval on query results will be faster.
SetThumbnailPrefetch(ThumbnailMode, UInt32, ThumbnailOptions)	Specifies the type and size of thumbnails that the system should start loading immediately when items are accessed (instead of retrieving them on a case-by-case basis). This uses more resources but makes thumbnail retrieval on query results faster.

See also

• File search sample (Windows 10)
• Folder enumeration sample