Query​Options Query​Options Query​Options 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
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

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.

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

Constructors

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()
Attributes

QueryOptions(CommonFileQuery, IIterable<String>) QueryOptions(CommonFileQuery, IIterable<String>) 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.

public QueryOptions(CommonFileQuery query, IIterable<String> fileTypeFilter)public QueryOptions(CommonFileQuery query, IIterable<String> fileTypeFilter)Public Sub New(query As CommonFileQuery, fileTypeFilter As IIterable<String>)
Parameters
query
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

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 "*".

Attributes

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)
Parameters
query
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.

Attributes

Properties

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

Attributes

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

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

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

Attributes

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 IVector<string> FileTypeFilter { get; }Public ReadOnly Property FileTypeFilter As IVector<string>
Value

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.

Attributes

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

Attributes

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
Value
string string string

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

Attributes

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

The indexer option.

Attributes

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
Value
string string string

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

Attributes

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 IVector<SortEntry> SortOrder { get; }Public ReadOnly Property SortOrder As IVector<SortEntry>
Value

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

Attributes

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.

StorageProviderIdFilter StorageProviderIdFilter StorageProviderIdFilter

Gets the filter for storage provider identifiers.

public IVector<string> StorageProviderIdFilter { get; }public IVector<string> StorageProviderIdFilter { get; }Public ReadOnly Property StorageProviderIdFilter As IVector<string>
Value

The filter string.

Attributes

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

Attributes

Remarks

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

Methods

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(String value)public void LoadFromString(String value)Public Function LoadFromString(value As String) As void
Parameters
value
System.String System.String System.String

A string retrieved by a previous call to SaveToString.

Attributes

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
Returns
string string string

A string representing the serialized settings of a QueryOptions instance.

Attributes

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.

SetPropertyPrefetch(PropertyPrefetchOptions, IIterable<String>) SetPropertyPrefetch(PropertyPrefetchOptions, IIterable<String>) 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.

public void SetPropertyPrefetch(PropertyPrefetchOptions options, IIterable<String> propertiesToRetrieve)public void SetPropertyPrefetch(PropertyPrefetchOptions options, IIterable<String> propertiesToRetrieve)Public Function SetPropertyPrefetch(options As PropertyPrefetchOptions, propertiesToRetrieve As IIterable<String>) As void
Parameters
options
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

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.

Attributes
See Also

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, UInt32 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
Parameters
mode
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
System.UInt32 System.UInt32 System.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

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.

Attributes
See Also

See Also