Specifies the parameters of a search query for enumerating the contents of storage folders.
Syntax
var queryOptions = new Windows.Storage.Search.QueryOptions(); var queryOptions = new Windows.Storage.Search.QueryOptions(query); var queryOptions = new Windows.Storage.Search.QueryOptions(query, fileTypeFilter);
Attributes
- ActivatableAttribute(Windows.Storage.Search.IQueryOptionsFactory, NTDDI_WIN8)
- ActivatableAttribute(NTDDI_WIN8)
- MarshalingBehaviorAttribute(Agile)
- VersionAttribute(NTDDI_WIN8)
Members
The QueryOptions class has these types of members:
Constructors
The QueryOptions class has these constructors.
| Constructor | Description |
|---|---|
| QueryOptions() | Creates an instance of the QueryOptions class for enumerating storage items, and initializes it with the following default settings: QueryOptions.FolderDepth gets FolderDepth.ShallowQueryOptions.IndexerOption gets IndexerOption.DoNotUseIndexer |
| 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. |
Methods
The QueryOptions class has these methods. With C#, Visual Basic, and C++, it also inherits methods from the Object class.
| Method | Description |
|---|---|
| LoadFromString | 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 | 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). |
| SetThumbnailPrefetch | 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). |
Properties
The QueryOptions class has these properties.
| Property | Access type | Description |
|---|---|---|
| Read/write | 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. | |
| Read-only | Gets the unit of time used to group files into folders if the QueryOptions object was created with a CommonFolderQuery based on date. | |
| Read-only | Gets a list of file name extensions used to filter the search results. If the list is empty, the results include all file types. | |
| Read/write | Indicates whether the search query should produce a shallow view of the folder contents or a deep recursive view of all files and subfolder. | |
| Read-only | Gets the name of the property used to group query results if the QueryOptions object was created using a CommonFolderQuery. | |
| Read/write | Gets or sets a value that specifies whether the system index or the file system is used to retrieve query results. | |
| Read/write | 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. | |
| Read-only | Gets the list of SortEntry structures that specify how to sort content (like files and subfolders) in query results. | |
| Read/write | 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. |
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.
For more code examples that show you how to use QueryOptions, see the Folder enumeration sample and the File system search sample.
For more code samples about accessing properties, see the File access sample.
Windows Phone 8
This API is not implemented and will throw an exception if called.
Examples
This example demonstrates how to use QueryOptions to query files in a location.
// Set query options with filter and sort order for results var fileTypeFilter = [".jpg", ".png", ".bmp", ".gif"]; var queryOptions = new Windows.Storage.Search.QueryOptions(search.CommonFileQuery.orderByName, fileTypeFilter); // Create query and retrieve files var query = Windows.Storage.KnownFolders.picturesLibrary.createFileQueryWithOptions(queryOptions); query.getFilesAsync().done(function (files) { // Process results files.forEach(function (file) { // Process file }); });
The previous example relies on the Pictures library capability through PicturesLibrary to get a StorageFolder object. To learn more about accessing files and folders, see File access and permissions in Windows Store apps.
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).
// Create index backed file query and get results var documentsLibrary = Windows.Storage.KnownFolders.documentsLibrary; var fileTypeFilter = [".docx"]; var queryOptions = new Windows.Storage.Search.QueryOptions(Windows.Storage.Search.CommonFileQuery.orderByName, fileTypeFilter); queryOptions.indexerOption = Windows.Storage.Search.IndexerOption.onlyUseIndexer; var fileQuery = documentsLibrary.createFileQueryWithOptions(queryOptions); fileQuery.getFilesAsync().then(function (files) { // Process resulting files if (files.size === 0) { // Perform tasks to handle no files found } else { // Access properties for each file files.forEach(function (file) { // Get document properties file.properties.getDocumentPropertiesAsync().done(function (documentProperties) { // Perform tasks with document properties var title = documentProperties.title; }); }); } }, // Handle errors with an error function function (error) { // Handle errors encountered while processing files });
The previous example relies on the Documents library capability through DocumentsLibrary to get a StorageFolder object. To learn more about accessing files and folders, see File access and permissions in Windows Store apps.
In the example, file contains a StorageFile that represents the file to retrieve properties for.
Requirements
|
Minimum supported client | Windows 8 [Windows Store apps only] |
|---|---|
|
Minimum supported server | Windows Server 2012 [Windows Store apps only] |
|
Minimum supported phone | Windows Phone 8 |
|
Namespace |
|
|
Metadata |
|
Build date: 2/25/2013