QueryOptions QueryOptions QueryOptions QueryOptions Class

Definition

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

public : sealed class QueryOptions : IQueryOptions, IQueryOptionsWithProviderFilterpublic sealed class QueryOptions : IQueryOptions, IQueryOptionsWithProviderFilterPublic NotInheritable Class QueryOptions Implements IQueryOptions, IQueryOptionsWithProviderFilter// You can use this class in JavaScript.
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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
}

// 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
    });
});

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
}

// Create index backed file query and get results
var picturesLibrary = Windows.Storage.KnownFolders.picturesLibrary;
var fileTypeFilter = [".png"];
var queryOptions = new Windows.Storage.Search.QueryOptions(Windows.Storage.Search.CommonFileQuery.orderByName, fileTypeFilter);
queryOptions.indexerOption = Windows.Storage.Search.IndexerOption.onlyUseIndexer;
var fileQuery = picturesLibrary.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
});

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() QueryOptions() QueryOptions() 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.

public : QueryOptions()public QueryOptions()Public Sub New()// You can use this method in JavaScript.
See Also

QueryOptions(CommonFileQuery, IIterable) QueryOptions(CommonFileQuery, IIterable) QueryOptions(CommonFileQuery, IIterable) QueryOptions(CommonFileQuery, IIterable)

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.

public : QueryOptions(CommonFileQuery query, IIterable<PlatForm::String> fileTypeFilter)public QueryOptions(CommonFileQuery query, IEnumerable<String> fileTypeFilter)Public Sub New(query As CommonFileQuery, fileTypeFilter As IEnumerable<String>)// You can use this method in JavaScript.
Parameters
query
CommonFileQuery CommonFileQuery CommonFileQuery CommonFileQuery

An enumeration value that specifies the search parameters to use to query files.

The CommonFileQuery enumeration provides search parameters for several common types of file queries. For example, deep queries that retrieve all the files in the folder where the query is created or shallow queries that retrieve only the files in the top-level of the folder. The enumeration also determines how query results are sorted.

fileTypeFilter
IIterable<PlatForm::String> IEnumerable<String> IEnumerable<String> IEnumerable<String>

An array of file types to be included in the query results. To include all file types, supply null, an empty array, or an array containing a single entry of "*".

See Also

QueryOptions(CommonFolderQuery) QueryOptions(CommonFolderQuery) QueryOptions(CommonFolderQuery) QueryOptions(CommonFolderQuery)

Creates an instance of the QueryOptions class for enumerating subfolders and initializes it with values based on the specified CommonFolderQuery.

public : QueryOptions(CommonFolderQuery query)public QueryOptions(CommonFolderQuery query)Public Sub New(query As CommonFolderQuery)// You can use this method in JavaScript.
Parameters
query
CommonFolderQuery CommonFolderQuery CommonFolderQuery CommonFolderQuery

An enumeration value that specifies how to group the contents of the folder where the query is created into subfolders to enumerate. The subfolders that are retrieved using a CommonFolderQuery can be actual file system folders or virtual folders that represent groups of files (which are determined by the CommonFolderQuery value). For example, the CommonFolderQuery.GroupByArtist uses the Artist of the files in the folder (and its subfolders) to group files, creating one virtual folder (or file group) for each artist.

See Also

Properties

ApplicationSearchFilter ApplicationSearchFilter ApplicationSearchFilter 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.

public : PlatForm::String ApplicationSearchFilter { get; set; }public string ApplicationSearchFilter { get; set; }Public ReadWrite Property ApplicationSearchFilter As string// You can use this property in JavaScript.
Value
PlatForm::String string string string

A simple keyword, or a string that conforms to Advanced Query Syntax (AQS). For more information, see Using Advanced Query Syntax Programmatically.

Remarks

The application search filter should always use locale-invariant Advanced Query Syntax (AQS) syntax (such as System.FileName instead of "filename" (because the term "filename" that is associated with the property System.FileName is localized differently in different languages). This will ensure that the query returns the expected results on systems with non-English locales. Windows builds the search query by combining this property with the UserSearchFilter property.

DateStackOption DateStackOption DateStackOption 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.

public : DateStackOption DateStackOption { get; }public DateStackOption DateStackOption { get; }Public ReadOnly Property DateStackOption As DateStackOption// You can use this property in JavaScript.
Value
DateStackOption DateStackOption DateStackOption DateStackOption

The unit of time user to group folder content by date.

FileTypeFilter FileTypeFilter FileTypeFilter 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.

public : IVector<string> FileTypeFilter { get; }public IList<string> FileTypeFilter { get; }Public ReadOnly Property FileTypeFilter As IList<string>// You can use this property in JavaScript.
Value
IVector<PlatForm::String> IList<string> IList<string> IList<string>

The list of file types of files include in query results. The default value is an empty list (which is equivalent to a list containing only "*") that includes all file types.

FolderDepth FolderDepth FolderDepth 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.

public : FolderDepth FolderDepth { get; set; }public FolderDepth FolderDepth { get; set; }Public ReadWrite Property FolderDepth As FolderDepth// You can use this property in JavaScript.
Value
FolderDepth FolderDepth FolderDepth FolderDepth

A value that indicates how deeply to query the folder. The default value is FolderDepth.Shallow. Predefined queries typically override this property and change it to FolderDepth.Deep.

GroupPropertyName GroupPropertyName GroupPropertyName 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.

public : PlatForm::String GroupPropertyName { get; }public string GroupPropertyName { get; }Public ReadOnly Property GroupPropertyName As string// You can use this property in JavaScript.
Value
PlatForm::String string string string

The property that is being used to group files and that is specified by the CommonFolderQuery enumeration.

See Also

IndexerOption IndexerOption IndexerOption 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.

public : IndexerOption IndexerOption { get; set; }public IndexerOption IndexerOption { get; set; }Public ReadWrite Property IndexerOption As IndexerOption// You can use this property in JavaScript.

Language Language Language 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.

public : PlatForm::String Language { get; set; }public string Language { get; set; }Public ReadWrite Property Language As string// You can use this property in JavaScript.
Value
PlatForm::String string string string

The Internet Engineering Task Force (IETF) BCP47-standard language tag.

SortOrder SortOrder SortOrder 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.

public : IVector<SortEntry> SortOrder { get; }public IList<SortEntry> SortOrder { get; }Public ReadOnly Property SortOrder As IList<SortEntry>// You can use this property in JavaScript.
Value
IVector<SortEntry> IList<SortEntry> IList<SortEntry> IList<SortEntry>

A SortEntryVector that contains SortEntry structures. These structures specify how to sort query results.

Remarks

If the folder being queried is not in a library or in the HomeGroup folder, SortOrder only supports entries based on the System.ItemNameDisplay (PKEY_ItemNameDisplay), System.Search.Rank (PKEY_Search_Rank), or System.DateModified (PKEY_DateModified) properties; SortOrder entries based on any other properties will return E_INVALIDARG.

See Also

StorageProviderIdFilter StorageProviderIdFilter StorageProviderIdFilter StorageProviderIdFilter

Gets the filter for storage provider identifiers.

public : IVector<string> StorageProviderIdFilter { get; }public IList<string> StorageProviderIdFilter { get; }Public ReadOnly Property StorageProviderIdFilter As IList<string>// You can use this property in JavaScript.
Value
IVector<PlatForm::String> IList<string> IList<string> IList<string>

The filter string.

UserSearchFilter UserSearchFilter UserSearchFilter 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.

public : PlatForm::String UserSearchFilter { get; set; }public string UserSearchFilter { get; set; }Public ReadWrite Property UserSearchFilter As string// You can use this property in JavaScript.
Value
PlatForm::String string string string

A simple keyword or a string that conforms to Advanced Query Syntax (AQS). For more information, see Using Advanced Query Syntax Programmatically.

Remarks

Windows builds the search query by combining this property with the ApplicationSearchFilter property.

Methods

LoadFromString(String) LoadFromString(String) LoadFromString(String) LoadFromString(String)

Initializes the current instance of the QueryOptions class with search parameters specified by a string that was created by the SaveToString method.

public : void LoadFromString(PlatForm::String value)public void LoadFromString(String value)Public Function LoadFromString(value As String) As void// You can use this method in JavaScript.
Parameters
value
PlatForm::String String String String

A string retrieved by a previous call to SaveToString.

SaveToString() SaveToString() SaveToString() 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.

public : PlatForm::String SaveToString()public string SaveToString()Public Function SaveToString() As string// You can use this method in JavaScript.
Returns
PlatForm::String string string string

A string representing the serialized settings of a QueryOptions instance.

Remarks

Use this method if you want to save the query options for later use. For example if you generate query options dynamically based on user input and you want to preserve these options when your app is suspended. In this case, you should also use the FutureAccessList to persist access to the folder(s) where the query was created.

See Also

SetPropertyPrefetch(PropertyPrefetchOptions, IIterable) SetPropertyPrefetch(PropertyPrefetchOptions, IIterable) SetPropertyPrefetch(PropertyPrefetchOptions, IIterable) SetPropertyPrefetch(PropertyPrefetchOptions, IIterable)

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.

public : void SetPropertyPrefetch(PropertyPrefetchOptions options, IIterable<PlatForm::String> propertiesToRetrieve)public void SetPropertyPrefetch(PropertyPrefetchOptions options, IEnumerable<String> propertiesToRetrieve)Public Function SetPropertyPrefetch(options As PropertyPrefetchOptions, propertiesToRetrieve As IEnumerable<String>) As void// You can use this method in JavaScript.
Parameters
options
PropertyPrefetchOptions PropertyPrefetchOptions PropertyPrefetchOptions PropertyPrefetchOptions

A value that specifies the set of properties to retrieve in advance.

The possible property sets match the sets of properties available on from the StorageFile class. For example, PropertyPrefetchOptions.BasicProperties will retrieve all of the properties available through StorageFile.GetBasicPropertiesAsync in advance.

propertiesToRetrieve
IIterable<PlatForm::String> IEnumerable<String> IEnumerable<String> IEnumerable<String>

A custom list of properties to retrieve in advance as an array of property names. Use the system property names to specify properties, for example System.Copyright and System.Image.ColorSpace.

A list of additional properties to retrieve.

See Also

SetThumbnailPrefetch(ThumbnailMode, UInt32, ThumbnailOptions) SetThumbnailPrefetch(ThumbnailMode, UInt32, ThumbnailOptions) SetThumbnailPrefetch(ThumbnailMode, UInt32, ThumbnailOptions) 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.

public : void SetThumbnailPrefetch(ThumbnailMode mode, unsigned int requestedSize, ThumbnailOptions options)public void SetThumbnailPrefetch(ThumbnailMode mode, UInt32 requestedSize, ThumbnailOptions options)Public Function SetThumbnailPrefetch(mode As ThumbnailMode, requestedSize As UInt32, options As ThumbnailOptions) As void// You can use this method in JavaScript.
Parameters
mode
ThumbnailMode ThumbnailMode ThumbnailMode ThumbnailMode

The enumeration value that describes the purpose of the thumbnail and determines how the thumbnail image is adjusted.

For guidance about choosing the best thumbnail mode, see Guidelines and checklist for thumbnails.

requestedSize
unsigned int UInt32 UInt32 UInt32

The requested size, in pixels, of the longest edge of the thumbnail. Windows uses the requestedSize as a guide and tries to return a thumbnail image that can be scaled to the requested size without reducing the quality of the image.

If Windows can't find a thumbnail image that exactly meets the requested size, a larger thumbnail might be returned. If no larger thumbnail is available, a thumbnail image that is smaller than the requested size might be returned.

options
ThumbnailOptions ThumbnailOptions ThumbnailOptions ThumbnailOptions

The enum value that describes the desired behavior to use to retrieve the thumbnail image. The specified behavior might affect the size and/or quality of the image and how quickly the thumbnail image is retrieved.

See Also

See Also