QueryOptions QueryOptions QueryOptions QueryOptions Class

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

Syntax

Declaration

public sealed class QueryOptionspublic sealed class QueryOptionsPublic NotInheritable Class QueryOptionspublic sealed class QueryOptions

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

Creates an instance of the QueryOptions class for enumerating storage items, and initializes it with the following default settings: FolderDepth gets FolderDepth and IndexerOption gets IndexerOption.

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.

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.

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

Properties summary

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.

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 is used to create a QueryOptions object, the value of this property is DateStackOption.

Gets a list of file name extensions used to filter the search results. If the list is empty, the results include all file types.

Indicates whether the search query should produce a shallow view of the folder contents or a deep recursive view of all files and subfolder.

Gets the name of the property used to group query results if the QueryOptions object was created using a CommonFolderQuery. For example, if CommonFolderQuery is used to create a QueryOptions object, the value of this property is System.ItemDate.

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.

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.

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.

Gets the filter for storage provider identifiers.

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 summary

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

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

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.

Constructors

  • QueryOptions()
    QueryOptions()
    QueryOptions()
    QueryOptions()

    Creates an instance of the QueryOptions class for enumerating storage items, and initializes it with the following default settings: FolderDepth gets FolderDepth and IndexerOption gets IndexerOption.

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

    Parameters

    • query

      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 or an array containing a single entry of "*".

  • 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 New(CommonFolderQuery query)Public Sub New(query As CommonFolderQuery)public QueryOptions(CommonFolderQuery query)

    Parameters

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 string ApplicationSearchFilter { get; set; }public string ApplicationSearchFilter { get; set; }Public ReadWrite Property ApplicationSearchFilter As stringpublic string ApplicationSearchFilter { get; set; }

    Property Value

    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 is used to create a QueryOptions object, the value of this property is DateStackOption.

    public DateStackOption DateStackOption { get; }public DateStackOption DateStackOption { get; }Public ReadOnly Property DateStackOption As DateStackOptionpublic DateStackOption DateStackOption { get; }

    Property Value

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

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

  • 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 FolderDepthpublic FolderDepth FolderDepth { get; set; }

    Property Value

  • 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 is used to create a QueryOptions object, the value of this property is System.ItemDate.

    public string GroupPropertyName { get; }public string GroupPropertyName { get; }Public ReadOnly Property GroupPropertyName As stringpublic string GroupPropertyName { get; }

    Property Value

    • string
      string
      string
      string

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

  • 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 IndexerOptionpublic IndexerOption IndexerOption { get; set; }

    Property Value

  • 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 string Language { get; set; }public string Language { get; set; }Public ReadWrite Property Language As stringpublic string Language { get; set; }

    Property Value

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

    Property Value

    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
    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>public IVector<string> StorageProviderIdFilter { get; }

    Property Value

    • 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 string UserSearchFilter { get; set; }public string UserSearchFilter { get; set; }Public ReadWrite Property UserSearchFilter As stringpublic string UserSearchFilter { get; set; }

    Property Value

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

    Parameters

    • value
      System.String
      System.String
      System.String
      System.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(String).

    public string SaveToString()public string SaveToString()Public Function SaveToString() As stringpublic string SaveToString()

    Returns

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

  • SetPropertyPrefetch(PropertyPrefetchOptions, IIterable<String>)
    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 voidpublic void SetPropertyPrefetch(PropertyPrefetchOptions options, IIterable<String> propertiesToRetrieve)

    Parameters

  • 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, 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 voidpublic void SetThumbnailPrefetch(ThumbnailMode mode, UInt32 requestedSize, ThumbnailOptions options)

    Parameters

    • mode

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

      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.

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

Windows.Foundation.Metadata.ActivatableAttribute
Windows.Foundation.Metadata.ActivatableAttribute
Windows.Foundation.Metadata.ContractVersionAttribute
Windows.Foundation.Metadata.MarshalingBehaviorAttribute

Details

Assembly

Windows.Storage.Search.dll