StorageFolder.GetFoldersAsync Method

Reference

Definition

Namespace:: Windows.Storage

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Overloads

GetFoldersAsync()	Gets the subfolders in the current folder.
GetFoldersAsync(CommonFolderQuery)	Gets the subfolders in the current folder. When the value of the query argument is something other than CommonFolderQuery.DefaultQuery, gets a list of virtual folders that represent containers for groups of files in the subfolders of the current folder. Files are grouped into folders based on the specified value from the CommonFolderQuery enumeration.
GetFoldersAsync(CommonFolderQuery, UInt32, UInt32)	Gets an index-based range of folders from the list of all subfolders in the current folder. When the value of the query argument is something other than CommonFolderQuery.DefaultQuery, gets a list of virtual folders that represent containers for groups of files in the subfolders of the current folder. Files are grouped into folders based on the specified value from the CommonFolderQuery enumeration.

GetFoldersAsync()

Edit

Gets the subfolders in the current folder.

public:
 virtual IAsyncOperation<IVectorView<StorageFolder ^> ^> ^ GetFoldersAsync() = GetFoldersAsync;

/// [Windows.Foundation.Metadata.Overload("GetFoldersAsyncOverloadDefaultOptionsStartAndCount")]
/// [Windows.Foundation.Metadata.RemoteAsync]
IAsyncOperation<IVectorView<StorageFolder>> GetFoldersAsync();

[Windows.Foundation.Metadata.Overload("GetFoldersAsyncOverloadDefaultOptionsStartAndCount")]
[Windows.Foundation.Metadata.RemoteAsync]
public IAsyncOperation<IReadOnlyList<StorageFolder>> GetFoldersAsync();

function getFoldersAsync()

Public Function GetFoldersAsync () As IAsyncOperation(Of IReadOnlyList(Of StorageFolder))

Returns

IAsyncOperation<IVectorView<StorageFolder>>

IAsyncOperation<IReadOnlyList<StorageFolder>>

When this method completes successfully, it returns a list of the subfolders in the current folder. The list is of type IReadOnlyList<StorageFolder>. Each folder in the list is represented by a StorageFolder object.

Implements

GetFoldersAsync()

Attributes: OverloadAttribute RemoteAsyncAttribute

Exceptions

UnauthorizedAccessException

You don't have permission to access the contents of the current folder. For more information, see File access permissions.

Examples

The following example shows how to get the contents of the subfolders in the user's Pictures folder, grouped by month, by calling the GetFoldersAsync(CommonFolderQuery, UInt32, UInt32) method. (Files from the root of the current folder are not included.) This example returns a maximum of 4 folders, starting with the folder at index 0. Since the CommonFolderQuery.GroupByMonth option sorts dates in descending order (that is, from newest to oldest), this example returns folders for the 4 most recent months for which the user has photos. Each folder contains all the user's photos from that month.

Before you run the following example, enable the Pictures Library capability in the app manifest file.

using Windows.Storage;
using Windows.Storage.Search;
using System.Threading.Tasks;
using System.Diagnostics; // For writing results to Output window.

// Get the user's Pictures folder.
// Enable the corresponding capability in the app manifest file.
StorageFolder picturesFolder = KnownFolders.PicturesLibrary;

// Get the files in the subfolders of the user's Pictures folder,
// grouped by month. Get only the first 4 folders (months).
IReadOnlyList <StorageFolder> groupedItems = await picturesFolder.GetFoldersAsync(CommonFolderQuery.GroupByMonth, 0, 4);

// Iterate over the results and print the list of folders
// and files to the Visual Studio Output window.
foreach (StorageFolder folder in groupedItems)
{
    Debug.WriteLine(folder.Name);

    // To iterate over the files in each folder, uncomment the following lines. 
    // foreach(StorageFile file in await folder.GetFilesAsync())
    //    Debug.WriteLine(" " + file.Name);
}

IAsyncAction MainPage::ExampleCoroutineAsync()
{
    // Get the users's Pictures folder.
    // Enable the Pictures Library capability in the app manifest file.
    Windows::Storage::StorageFolder picturesFolder{ Windows::Storage::KnownFolders::PicturesLibrary() };

    // Get the files in the user's Pictures folder, grouped by month.
    // Get only the first 4 folders (months).
    Windows::Foundation::Collections::IVectorView<Windows::Storage::StorageFolder> itemsInFolder{
        co_await picturesFolder.GetFoldersAsync(Windows::Storage::Search::CommonFolderQuery::GroupByMonth, 0, 4) };

    // Iterate over the results, and print the list of file groups to the Visual Studio output window.
    for (StorageFolder const& itemInFolder : itemsInFolder)
    {
        std::wstring output{ itemInFolder.Name() };
        ::OutputDebugString(output.c_str());
    }
}

// Get the user's Pictures folder.
// Enable the corresponding capability in the app manifest file.
StorageFolder^ picturesFolder = KnownFolders::PicturesLibrary;

// Get the files in the user's Pictures folder, grouped by month.
// Get only the first 4 folders (months).
create_task(picturesFolder->GetFoldersAsync(CommonFolderQuery::GroupByMonth, 0, 4)).then([=](IVectorView<StorageFolder^>^ itemsInFolder) {
 //Iterate over the results and print the list of file groups
 // to the visual studio output window
 for (auto it = itemsInFolder->First(); it->HasCurrent; it->MoveNext())
 {
  StorageFolder^ file = it->Current;
  String^ output = file->Name + "\n";
  OutputDebugString(output->Begin());
 }
});

Remarks

This query is a shallow query that returns only subfolders in the current folder.

The following table lists methods of the StorageFolder class that get a list of subfolders. The table identifies shallow queries that only return subfolders from the current folder, and deep queries that return the contents of nested subfolders, grouped into virtual folders.

Some methods take a value from the CommonFolderQuery enumeration.

When you use the DefaultQuery option with any folder, the query returns a list of subfolders in the file system.
When you use an option other than DefaultQuery with a library folder, the query returns a list of virtual folders that represent containers for files from the subfolders of the current folder. (Files from the current folder are not included.) The files are grouped into virtual folders based on the specified value from the CommonFolderQuery enumeration. For example, if you specify GroupByMonth, the query returns a list of virtual folders such as July 2014, August 2014, and September 2014.

Tip

You can use the DefaultQuery option with any folder; you can use the other options from the CommonFolderQuery enumeration only with library folders, such as the Pictures library, or the Homegroup folder.

To get deep query results from a folder that's not a library folder, call the CreateFolderQueryWithOptions(QueryOptions) method and specify Deep as the value of the FolderDepth property of the QueryOptions object.

Method	Create a shallow query that only returns subfolders from the current folder	Create a deep query that returns all nested subfolders
GetFoldersAsync()	Default behavior of this method.	N/A
GetFoldersAsync(CommonFileQuery)	Specify the DefaultQuery option.	For a library folder, specify an option other than DefaultQuery.
GetFoldersAsync(CommonFileQuery, UInt32, UInt32)	Specify the DefaultQuery option.	For a library folder, specify an option other than DefaultQuery.
CreateFolderQuery()	Default behavior of this method.	N/A
CreateFolderQuery(CommonFileQuery)	Specify the DefaultQuery option.	For a library folder, specify an option other than DefaultQuery.
CreateFolderQueryWithOptions(QueryOptions)	Default behavior of this method if none of the following options are specified. - or - Specify DefaultQuery as the value of CommonFolderQuery when you instantiate the QueryOptions object. - or - Specify Shallow as the value of the FolderDepth property of the QueryOptions object.	For a library folder, specify a value other than DefaultQuery as the value of CommonFolderQuery when you instantiate the QueryOptions object. - or - For any folder, specify Deep as the value of the FolderDepth property of the QueryOptions.

Applies to

GetFoldersAsync(CommonFolderQuery)

Edit

Gets the subfolders in the current folder. When the value of the query argument is something other than CommonFolderQuery.DefaultQuery, gets a list of virtual folders that represent containers for groups of files in the subfolders of the current folder. Files are grouped into folders based on the specified value from the CommonFolderQuery enumeration.

public:
 virtual IAsyncOperation<IVectorView<StorageFolder ^> ^> ^ GetFoldersAsync(CommonFolderQuery query) = GetFoldersAsync;

/// [Windows.Foundation.Metadata.Overload("GetFoldersAsyncOverloadDefaultStartAndCount")]
/// [Windows.Foundation.Metadata.RemoteAsync]
IAsyncOperation<IVectorView<StorageFolder>> GetFoldersAsync(CommonFolderQuery const& query);

[Windows.Foundation.Metadata.Overload("GetFoldersAsyncOverloadDefaultStartAndCount")]
[Windows.Foundation.Metadata.RemoteAsync]
public IAsyncOperation<IReadOnlyList<StorageFolder>> GetFoldersAsync(CommonFolderQuery query);

function getFoldersAsync(query)

Public Function GetFoldersAsync (query As CommonFolderQuery) As IAsyncOperation(Of IReadOnlyList(Of StorageFolder))

Parameters

query: CommonFolderQuery

One of the enumeration values that specifies how to group the files into folders and determines whether the query is shallow or deep.

Returns

IAsyncOperation<IVectorView<StorageFolder>>

IAsyncOperation<IReadOnlyList<StorageFolder>>

When this method completes successfully, it returns a list of subfolders. When the value of the query argument is something other than CommonFolderQuery.DefaultQuery, this method returns a list of virtual folders that represent containers for groups of files in the subfolders of the current folder. (Files from the current folder are not included.) The files are grouped as specified by query. The list is of type IReadOnlyList<StorageFolder>. Each folder in the list is represented by a StorageFolder object.

Implements

GetFoldersAsync(CommonFolderQuery)

Attributes: OverloadAttribute RemoteAsyncAttribute

Exceptions

UnauthorizedAccessException

You don't have permission to access the contents of the current folder. For more information, see File access permissions.

Applies to

GetFoldersAsync(CommonFolderQuery, UInt32, UInt32)

Edit

Gets an index-based range of folders from the list of all subfolders in the current folder. When the value of the query argument is something other than CommonFolderQuery.DefaultQuery, gets a list of virtual folders that represent containers for groups of files in the subfolders of the current folder. Files are grouped into folders based on the specified value from the CommonFolderQuery enumeration.

public:
 virtual IAsyncOperation<IVectorView<StorageFolder ^> ^> ^ GetFoldersAsync(CommonFolderQuery query, unsigned int startIndex, unsigned int maxItemsToRetrieve) = GetFoldersAsync;

/// [Windows.Foundation.Metadata.Overload("GetFoldersAsync")]
/// [Windows.Foundation.Metadata.RemoteAsync]
IAsyncOperation<IVectorView<StorageFolder>> GetFoldersAsync(CommonFolderQuery const& query, uint32_t const& startIndex, uint32_t const& maxItemsToRetrieve);

[Windows.Foundation.Metadata.Overload("GetFoldersAsync")]
[Windows.Foundation.Metadata.RemoteAsync]
public IAsyncOperation<IReadOnlyList<StorageFolder>> GetFoldersAsync(CommonFolderQuery query, uint startIndex, uint maxItemsToRetrieve);

function getFoldersAsync(query, startIndex, maxItemsToRetrieve)

Public Function GetFoldersAsync (query As CommonFolderQuery, startIndex As UInteger, maxItemsToRetrieve As UInteger) As IAsyncOperation(Of IReadOnlyList(Of StorageFolder))

Parameters

query: CommonFolderQuery

One of the enumeration values that specifies how to group the files into folders and determines whether the query is shallow or deep.

startIndex: UInt32
unsigned int

uint32_t

The zero-based index of the first folder in the range to retrieve.

maxItemsToRetrieve: UInt32
unsigned int

uint32_t

The maximum number of folders to retrieve.

Returns

IAsyncOperation<IVectorView<StorageFolder>>

IAsyncOperation<IReadOnlyList<StorageFolder>>

Implements

M:Windows.Storage.Search.IStorageFolderQueryOperations.GetFoldersAsync(Windows.Storage.Search.CommonFolderQuery,System.UInt32,System.UInt32) M:Windows.Storage.Search.IStorageFolderQueryOperations.GetFoldersAsync(Windows.Storage.Search.CommonFolderQuery,unsigned int,unsigned int) M:Windows.Storage.Search.IStorageFolderQueryOperations.GetFoldersAsync(Windows.Storage.Search.CommonFolderQuery,uint32_t,uint32_t)

Attributes: OverloadAttribute RemoteAsyncAttribute

Exceptions

UnauthorizedAccessException

You don't have permission to access the contents of the current folder. For more information, see File access permissions.

Applies to

Share via

StorageFolder.GetFoldersAsync Method

Definition

Overloads

GetFoldersAsync()

Returns

Implements

Exceptions

Examples

Remarks

See also

Applies to

GetFoldersAsync(CommonFolderQuery)

Parameters

Returns

Implements

Exceptions

See also

Applies to

GetFoldersAsync(CommonFolderQuery, UInt32, UInt32)

Parameters

Returns

Implements

Exceptions

See also

Applies to

Feedback

Additional resources