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
| 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.
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.
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.
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.
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.
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.
The indexer option.
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.
- 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.
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.
- 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.
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.
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