Storage​Folder​Query​Result Storage​Folder​Query​Result Storage​Folder​Query​Result Class


Provides access to the results of a query that lists the folder (or file groups) in the folder being queried (which is represented by a storageFolder ). You can use a storageFolderQueryResult to enumerate folders or file groups in that folder.

public : sealed class StorageFolderQueryResult : IStorageFolderQueryResult, IStorageQueryResultBasepublic sealed class StorageFolderQueryResult : IStorageFolderQueryResult, IStorageQueryResultBasePublic NotInheritable Class StorageFolderQueryResult Implements IStorageFolderQueryResult, IStorageQueryResultBase
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)


This example demonstrates how to get a list folders (or file groups) from a storageFolderQueryResult object.

// Get the Pictures library
Windows.Storage.StorageFolder picturesFolder = Windows.Storage.KnownFolders.PicturesLibrary;

// Set query options to create groups of files within result
QueryOptions queryOptions = new QueryOptions(Windows.Storage.Search.CommonFolderQuery.GroupByMonth);

// Create query and retrieve result
StorageFolderQueryResult queryResult = picturesLibrary.CreateFolderQueryWithOptions(queryOptions);
IReadOnlyList<StorageFolder> folders = await queryResult.GetFoldersAsync();
// Process file groups
foreach (StorageFolder folder in folders)
    // Get and process files in group
    IReadOnlyList<StorageFile> fileList = await folder.GetFilesAsync();
    OutputPanel.Children.Add(CreateHeaderTextBlock(folder.Name + " (" + fileList.Count + ")"));
    foreach (StorageFile file in fileList)
        // Process file

// Get the Pictures library, then rearrange it by month
var picturesLibrary = Windows.Storage.KnownFolders.picturesLibrary;

// Set query options to create groups of files within result
var queryOptions = new QueryOptions(Windows.Storage.Search.CommonFolderQuery.GroupByMonth);

// Create query and retrieve result
var queryResult = picturesLibrary.createFolderQuery(Windows.Storage.Search.CommonFolderQuery.groupByMonth);
queryResult.getFoldersAsync().done(function(folders) {
    // Process file groups (or folders)

    // Create an array of promises that will asynchronously
    // retrieve the files for each file group
    var promises = (folder) {
        return folder.getFilesAsync();

    // Aggregate the results of multiple asynchronous operations
    // so that they are returned after all are completed. This
    // ensures that the groups are displayed in order.
    WinJS.Promise.join(promises).done(function (folderContents) {
        // Process the contents of each file group (or folder)

        for (var i in folderContents) {
            // Process the group/folder at index i of folderContents

            // Display the group name
            var group = outputResultGroup(folders.getAt(i).name);
            // Display the items in the group 
            outputItems(group, folderContents[i]);

The queryResult variable gets the storageFolderQueryResult that is used to retrieve file groups (or folders) that meet the criteria of the query.


You need the Pictures library capability to access the library using KnownFolders.PicturesLibrary. To learn more about capabilities and file access, see File access permissions.



Although it's not attributed with marshalling_behavior(agile), this class can be treated as agile. For more info, see Threading and Marshaling (C++/CX).

You can get a storageFolderQueryResult object by calling the following methods from a storageFolder or a folderInformation object:

To get a StorageFolderQueryResult object to enumerate the folders or file groups in a location, you must get a storageFolder that represents the location and then create a folder query


Folder Folder Folder

Gets the folder originally used to create the StorageFolderQueryResult object. This folder represents the scope of the query.

public : StorageFolder Folder { get; }public StorageFolder Folder { get; }Public ReadOnly Property Folder As StorageFolder
StorageFolder StorageFolder StorageFolder

The original folder.



ApplyNewQueryOptions(QueryOptions) ApplyNewQueryOptions(QueryOptions) ApplyNewQueryOptions(QueryOptions)

Modifies query results based on new QueryOptions.

public : void ApplyNewQueryOptions(QueryOptions newQueryOptions)public void ApplyNewQueryOptions(QueryOptions newQueryOptions)Public Function ApplyNewQueryOptions(newQueryOptions As QueryOptions) As void
QueryOptions QueryOptions QueryOptions

The new query options.



This method causes the OptionsChanged event to fire.

When this method returns, subsequent calls to GetFoldersAsync or GetItemCountAsync will reflect the results of the new QueryOptions.

FindStartIndexAsync(Object) FindStartIndexAsync(Object) FindStartIndexAsync(Object)

Retrieves the index of the folder from the query results that most closely matches the specified property value. The property that is matched is determined by the first SortEntry of the QueryOptions.SortOrder list.

public : IAsyncOperation<unsigned short> FindStartIndexAsync(PlatForm::Object value)public IAsyncOperation<uint> FindStartIndexAsync(Object value)Public Function FindStartIndexAsync(value As Object) As IAsyncOperation( Of uint )
PlatForm::Object Object Object

The property value to match when searching the query results. The property to that is used to match this value is the property in the first SortEntry of the QueryOptions.SortOrder list.

IAsyncOperation<unsigned short> IAsyncOperation<uint> IAsyncOperation<uint>

When this method completes successfully it returns the index of the matched folder in the query results; otherwise it returns uint.MaxValue.



This example shows how to find the first album that has a title that begins with an "R" in a set of query results that contains albums sorted by title.

QueryOptions queryOptions = new QueryOptions();
queryOptions.FolderDepth = FolderDepth.Deep;
queryOptions.IndexerOption = IndexerOption.OnlyUseIndexer;
SortEntry album = new SortEntry();
album.AscendingOrder = true;
album.PropertyName = "System.Music.AlbumTitle";

StorageFolderQueryResult queryResult = musicFolder.CreateFolderQueryWithOptions(queryOptions);
var firstIndex = await queryResult.FindStartIndexAsync("R");
var queryOptions = new Windows.Storage.Search.QueryOptions();
queryOptions.folderDepth = Windows.Storage.Search.FolderDepth.deep;
queryOptions.indexerOption = Windows.Storage.Search.IndexerOptions.onlyUseIndexer;
 ascendingOrder: true,
 propertyName: "System.Music.AlbumTitle"

var queryResult = Windows.Storage.KnownFolders.picturesLibrary.createFolderQueryWithOptions(queryOptions);
var firstIndex = queryResult.findStartIndexAsync("R");

GetCurrentQueryOptions() GetCurrentQueryOptions() GetCurrentQueryOptions()

Retrieves the query options used to determine query results.

public : QueryOptions GetCurrentQueryOptions()public QueryOptions GetCurrentQueryOptions()Public Function GetCurrentQueryOptions() As QueryOptions

GetFoldersAsync() GetFoldersAsync() GetFoldersAsync()

Retrieves a list of all the folders (or file groups) in the result set.

public : IAsyncOperation<IVectorView<StorageFolder>> GetFoldersAsync()public IAsyncOperation<IReadOnlyList<StorageFolder>> GetFoldersAsync()Public Function GetFoldersAsync() As IAsyncOperation( Of IReadOnlyListStorageFolder )
IAsyncOperation<IVectorView<StorageFolder>> IAsyncOperation<IReadOnlyList<StorageFolder>> IAsyncOperation<IReadOnlyList<StorageFolder>>

When this method completes successfully, it returns a list (type IVectorView ) of folders or file groups that are represented by storageFolder objects. Each of these folder or file group can also be enumerated to retrieve its contents.

See Also

GetFoldersAsync(UInt32, UInt32) GetFoldersAsync(UInt32, UInt32) GetFoldersAsync(UInt32, UInt32)

Retrieves folders (or file groups) in a specified range.

public : IAsyncOperation<IVectorView<StorageFolder>> GetFoldersAsync(unsigned int startIndex, unsigned int maxNumberOfItems)public IAsyncOperation<IReadOnlyList<StorageFolder>> GetFoldersAsync(UInt32 startIndex, UInt32 maxNumberOfItems)Public Function GetFoldersAsync(startIndex As UInt32, maxNumberOfItems As UInt32) As IAsyncOperation( Of IReadOnlyListStorageFolder )
unsigned int UInt32 UInt32

The zero-based index of the first folder to retrieve. This parameter defaults to 0.

unsigned int UInt32 UInt32

The maximum number of folders or file groups to retrieve. Use -1 to retrieve all folders. If the range contains fewer folders than the max number, all folders in the range are returned.

IAsyncOperation<IVectorView<StorageFolder>> IAsyncOperation<IReadOnlyList<StorageFolder>> IAsyncOperation<IReadOnlyList<StorageFolder>>

When this method completes successfully, it returns a list (type IVectorView ) of folders or file groups that are represented by storageFolder objects.



Use this overload to improve system performance by presenting a virtualized view of the query results that includes only the necessary subset of folders. For example, if your app displays many folders in a gallery you could use this range to retrieve only the folders that are currently visible to the user.

See Also

GetItemCountAsync() GetItemCountAsync() GetItemCountAsync()

Retrieves the number of folders (or file groups) in the set of query results.

public : IAsyncOperation<unsigned short> GetItemCountAsync()public IAsyncOperation<uint> GetItemCountAsync()Public Function GetItemCountAsync() As IAsyncOperation( Of uint )
IAsyncOperation<unsigned short> IAsyncOperation<uint> IAsyncOperation<uint>

When this method completes successfully, it returns the number of folders or file groups in the location that match the query.

See Also


ContentsChanged ContentsChanged ContentsChanged

Fires when a file is added to, deleted from, or modified in the folder being queried. This event only fires after GetFilesAsync has been called at least once.

public : event TypedEventHandler ContentsChangedpublic event TypedEventHandler ContentsChangedPublic Event ContentsChanged


If you register a handler for this event, keep that handler registered while you suspend your app (in response to oncheckpoint or Suspending ). Your app will not receive ContentsChanged events while it is suspended and when your app resumes it will receive a single event that aggregates all of the changes if any occurred.

Additionally, keep in mind that registering and removing event handlers are synchronous operations and might cause your app to stop responding briefly if you execute them on your app's UI thread. Wherever possible, use a thread other than your app's UI thread to register and unregister these event handlers.

OptionsChanged OptionsChanged OptionsChanged

Fires when the query options change.

public : event TypedEventHandler OptionsChangedpublic event TypedEventHandler OptionsChangedPublic Event OptionsChanged

See Also