Storage​Folder Storage​Folder Storage​Folder Class

Gets the attributes of the current folder.

public FileAttributes Attributes { get; }public FileAttributes Attributes { get; }Public ReadOnly Property Attributes As FileAttributes

Attributes

ContractVersionAttribute StaticAttribute

Remarks

Examples

The following example shows how to check the attributes of a folder.

using Windows.Storage;
using System.Diagnostics; // For writing results to the Output window.

// Get the app's installation folder.
StorageFolder appFolder =
    Windows.ApplicationModel.Package.Current.InstalledLocation;

// Get the folder's attributes.
FileAttributes folderAttributes = appFolder.Attributes;

// Check the folder's attributes.
// Write the results to the Visual Studio Output window.
if ((folderAttributes & FileAttributes.ReadOnly) == FileAttributes.ReadOnly)
    Debug.WriteLine("The item is read-only.");
if ((folderAttributes & FileAttributes.Directory) == FileAttributes.Directory)
    Debug.WriteLine("The item is a folder.");
if ((folderAttributes & FileAttributes.Archive) == FileAttributes.Archive)
    Debug.WriteLine("The item is archived.");
if ((folderAttributes & FileAttributes.Temporary) == FileAttributes.Temporary)
    Debug.WriteLine("The item is temporary.");

Gets the date and time that the current folder was created.

public DateTime DateCreated { get; }public DateTimeOffset DateCreated { get; }Public ReadOnly Property DateCreated As DateTimeOffset

Attributes

ContractVersionAttribute StaticAttribute

Remarks

If the date property isn't set, this value defaults to 0 which can be translated into misleading dates in different programming languages. In JavaScript, for example, 0 translates to December 16, 1600. You should always check that this property is a real value and not 0.

Gets the user-friendly name of the current folder.

public PlatForm::String DisplayName { get; }public string DisplayName { get; }Public ReadOnly Property DisplayName As string

Attributes

ContractVersionAttribute StaticAttribute

Gets the user-friendly description of the type of the folder; for example, JPEG image.

public PlatForm::String DisplayType { get; }public string DisplayType { get; }Public ReadOnly Property DisplayType As string

Attributes

ContractVersionAttribute StaticAttribute

Remarks

For an ordinary folder in the file system, the DisplayType property returns File folder.

Here are some examples of the value of the DisplayType property when you use a CommonFolderQuery value other than DefaultQuery.

• If you specify GroupByType, the value of DisplayType may be JPEG image or PNG image. The folders have the same name as the display type.
• If you specify GroupByMonth, the value of DisplayType is Stack. The folders have names like October 2014 or November 2014.

Gets an identifier for the current folder. This ID is unique for the query result or StorageFolder that contains the current folder or file group, and can be used to distinguish between items that have the same name.

public PlatForm::String FolderRelativeId { get; }public string FolderRelativeId { get; }Public ReadOnly Property FolderRelativeId As string

Attributes

ContractVersionAttribute StaticAttribute

Remarks

You create a query result object when you create a query using one of the methods on a StorageFolder object. Depending on the method you call, your query result object could be a StorageFileQueryResult, a StorageFolderQueryResult, or a StorageItemQueryResult object.

Gets the name of the current folder.

public PlatForm::String Name { get; }public string Name { get; }Public ReadOnly Property Name As string

Attributes

ContractVersionAttribute StaticAttribute

Gets the full path of the current folder in the file system, if the path is available.

public PlatForm::String Path { get; }public string Path { get; }Public ReadOnly Property Path As string

Attributes

ContractVersionAttribute StaticAttribute

Remarks

Don't rely on this property to access a folder, because a file system path is not available for some folders. For example, in the following cases, the folder may not have a file system path, or the file system path may not be available.

• The folder represents a container for a group of files (for example, the return value from some overloads of the GetFoldersAsync method) instead of an actual folder in the file system.
• The folder is backed by a URI.
• The folder was picked by using a file picker.

Examples

The following example gets the app's installation folder and displays the value of the folder's Path.

using Windows.Storage;
using System.Diagnostics; // For writing results to the Output window.

// Get the app's installation folder.
StorageFolder appFolder = Windows.ApplicationModel.Package.Current.InstalledLocation;

// Print the folder's path to the Visual Studio Output window.
Debug.WriteLine(appFolder.Name + " folder path: " + appFolder.Path);

/ Get the app's installation folder.
var appFolder = Windows.ApplicationModel.Package.current.installedLocation;

// Print the folder's path to the Visual Studio Output window.
console.log(appFolder.name, "folder path:", appFolder.path);

 // Get the app's installation folder
 StorageFolder^ appFolder = Windows::ApplicationModel::Package::Current->InstalledLocation;

 //Print the path to the debug window
 String^ path = appFolder->Path;
 OutputDebugString(path->Begin());

Gets an object that provides access to the content-related properties of the current folder.

public StorageItemContentProperties Properties { get; }public StorageItemContentProperties Properties { get; }Public ReadOnly Property Properties As StorageItemContentProperties

Attributes

ContractVersionAttribute StaticAttribute

Gets the StorageProvider object that contains info about the service that stores the current folder.

public StorageProvider Provider { get; }public StorageProvider Provider { get; }Public ReadOnly Property Provider As StorageProvider

Attributes

ContractVersionAttribute StaticAttribute

Indicates whether the current folder supports the specified QueryOptions.

public PlatForm::Boolean AreQueryOptionsSupported(QueryOptions queryOptions)public bool AreQueryOptionsSupported(QueryOptions queryOptions)Public Function AreQueryOptionsSupported(queryOptions As QueryOptions) As bool

Attributes

ContractVersionAttribute StaticAttribute

Remarks

QueryOptions let you enumerate files in a folder and its subfolders by letting you specify criteria that you can then use to create a query result object of files in that folder and subfolders. The CommonFileQuery and CommonFolderQuery enumeration represent some of the most common criteria used to filter and enumerate files and folders.

Use the AreQueryOptionsSupported method to verify that the QueryOptions you want to specify are available for the current folder. You can also check whether a specific CommonFileQuery or CommonFolderQuery value is available, by calling IsCommonFileQuerySupported or IsCommonFolderQuerySupported, respectively.

The specific options available to you depend on where the files or folders that you want to enumerate are located. For folders and files that are located inside a library or homegroup, you can use any combination of QueryOptions.

Folders and files outside of a library or homegroup support a only subset of options.

• For queries that enumerate only the top-level files or folders (also known as a shallow query), create a QueryOptions object in one of the following three ways:

  • Call the default QueryOptions() constructor.
  • Call the QueryOptions(CommonFolderQuery) constructor and specify CommonFolderQuery.@Windows.Storage.Search.CommonFolderQuery?text=DefaultQuery.
  • Call the QueryOptions(CommonFileQuery, IIterable(String)) constructor and specify CommonFileQuery.@Windows.Storage.Search.CommonFileQuery?text=DefaultQuery. You can still specify file types to be filtered when you use this constructor.

• For queries that enumerate all of the files inside the current folder and its subfolders (also known as a deep query), create a QueryOptions object in one of the following two ways:

  • Call the QueryOptions(CommonFolderQuery) constructor and specify CommonFileQuery.@Windows.Storage.Search.CommonFileQuery?text=OrderByName or CommonFileQuery.@Windows.Storage.Search.CommonFileQuery?text=OrderBySearchRank.
  • Call the QueryOptions(CommonFileQuery, IIterable(String)) constructor and specify CommonFileQuery.@Windows.Storage.Search.CommonFileQuery?text=OrderByName or CommonFileQuery.@Windows.Storage.Search.CommonFileQuery?text=OrderBySearchRank. You can still specify file types to be filtered when you use this constructor.

For Windows Server 2012 You must install indexer components to use some QueryOptions, CommonFileQuery values, and CommonFolderQuery values because indexer components are not installed by default.

Creates a new file with the specified name in the current folder.

public IAsyncOperation<StorageFile> CreateFileAsync(String desiredName)public IAsyncOperation<StorageFile> CreateFileAsync(String desiredName)Public Function CreateFileAsync(desiredName As String) As IAsyncOperation( Of StorageFile )

Attributes

OverloadAttribute RemoteAsyncAttribute

Remarks

This method uses the FailIfExists value from the CreationCollisionOption enumeration by default. That is, this method raises an exception if a file with the same name already exists in the current folder. If you want to handle a file name collision in a different way, call the CreateFileAsync(String, CreationCollisionOption) method.

If you try to create a file in a virtual folder like a library, or a folder that represents a container for a group of files (for example, the return value from some overloads of the GetFoldersAsync method), the CreateFileAsync method may fail.

Examples

The following example shows how to create a new file in the current folder by calling the CreateFileAsync (String, CreationCollisionOption) overloaded method. This example explicitly specifies a value for options that causes the operation to fail if a file with the specified desiredName already exists in the current folder.

using Windows.Storage;
using System.Threading.Tasks;

// Get the app's local folder.
StorageFolder localFolder = Windows.Storage.ApplicationData.Current.LocalFolder;

// Create a new file in the current folder.
// Raise an exception if the file already exists.
string desiredName = "test.txt";
StorageFile newFile = await localFolder.CreateFileAsync(desiredName, CreationCollisionOption.FailIfExists);

// Get the app's local folder.
var localFolder = Windows.Storage.ApplicationData.current.localFolder;

// Create a new file in the current folder.
var desiredName = "test.txt";
var CreationCollisionOption = Windows.Storage.CreationCollisionOption;
var newFilePromise =
        localFolder.createFileAsync(desiredName, CreationCollisionOption.failIfExists);
newFilePromise.done(function createFileSuccess(newFile) 
{
    // CreateFile completed successfully.
}, function createFileFail(failure) 
{
    // CreateFile can fail if the file already exists.
});

//Gets the app's local folder
StorageFolder^ localFolder = ApplicationData::Current->LocalFolder;

//Create a new file in the current folder
// Raise an exception if the file already exists
String^ desiredName = "test.txt";
auto createFileTask = create_task(localFolder->CreateFileAsync(desiredName, Windows::Storage::CreationCollisionOption::FailIfExists));
createFileTask.then([](StorageFile^ newFile)
{
  //Do something with the new file.
 });

Creates a new file in the current folder. This method also specifies what to do if a file with the same name already exists in the current folder.

public IAsyncOperation<StorageFile> CreateFileAsync(String desiredName, CreationCollisionOption options)public IAsyncOperation<StorageFile> CreateFileAsync(String desiredName, CreationCollisionOption options)Public Function CreateFileAsync(desiredName As String, options As CreationCollisionOption) As IAsyncOperation( Of StorageFile )

Attributes

OverloadAttribute RemoteAsyncAttribute

Gets a query result object that contains the files in the current folder.

public StorageFileQueryResult CreateFileQuery()public StorageFileQueryResult CreateFileQuery()Public Function CreateFileQuery() As StorageFileQueryResult

Attributes

OverloadAttribute

Remarks

This query is a shallow query that returns only files in the current folder. For a list of methods that identifies shallow queries and deep queries, see the Remarks in the topic GetFilesAsync.

You can also get a list of files in the current folder asynchronously by calling one of the GetFilesAsync methods.

To specify additional query options, call the CreateFileQueryWithOptions method.

To get items that are files or folders, call the CreateItemQuery method.

Examples

The following example gets a query result object that contains the files in the current folder by calling the CreateFileQuery() method.

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

// Get the app's installation folder.
StorageFolder appFolder = Windows.ApplicationModel.Package.Current.InstalledLocation;

// Get the files in the current folder.
StorageFileQueryResult results = appFolder.CreateFileQuery();

// Iterate over the results and print the list of files
// to the Visual Studio Output window.
IReadOnlyList<StorageFile> filesInFolder = await results.GetFilesAsync();
foreach (StorageFile item in filesInFolder)
{
    Debug.WriteLine(item.Name);
}

// Get the app's installation folder.
var appFolder = Windows.ApplicationModel.Package.current.installedLocation;

// Get the files in the current folder.
var results = appFolder.createFileQuery();

// Iterate over the results and print the list of files
// to the Visual Studio Output window.
var filesInFolderPromise = results.getFilesAsync();
filesInFolderPromise.done(function getFilesSuccess(filesInFolder) {
    filesInFolder.forEach(function forEachFile(item) {
        console.log(item.name);
    });
});

 //Get the app's installation folder
 StorageFolder^ appFolder = Windows::ApplicationModel::Package::Current->InstalledLocation;
 //Get the files in the current folder
 StorageFileQueryResult^ results = appFolder->CreateFileQuery();

 create_task(results->GetFilesAsync()).then([=](IVectorView<StorageFile^>^ filesInFolder) {
  //Iterate over the results and print the list of files
  // to the visual studio output window
  for (auto it = filesInFolder->First(); it->HasCurrent; it->MoveNext())
  {
   StorageFile^ file = it->Current;
   String^ output = file->Name + "\n";
   OutputDebugString(output->Begin());
  }
 });

Gets a query result object that contains the files in the current folder. Also gets the files from the subfolders of the current folder when the value of the query argument is something other than CommonFileQuery.DefaultQuery. Files are sorted based on the specified CommonFileQuery.

public StorageFileQueryResult CreateFileQuery(CommonFileQuery query)public StorageFileQueryResult CreateFileQuery(CommonFileQuery query)Public Function CreateFileQuery(query As CommonFileQuery) As StorageFileQueryResult

Attributes

OverloadAttribute

Remarks

A CommonFileQuery sorts files based on specific file attributes (like title or date) quickly and easily.

When you specify the DefaultQuery option from the CommonFileQuery enumeration, this query is a shallow query that returns only files in the current folder. When you specify another value from the CommonFileQuery enumeration, this query is a deep query that returns a flattened list of files from the current folder and from its subfolders.

Tip

Some of the values from the CommonFileQuery enumeration can only be used with a library folder (such as the Pictures library) or the Homegroup folder. In addition to the DefaultQuery option, you can use only the OrderByName and OrderBySearchRank options with a folder that's not a library folder.

For a list of methods that identifies shallow queries and deep queries, see the Remarks in the topic GetFilesAsync.

To check whether a specific CommonFileQuery is available, call the folder's IsCommonFileQuerySupported method.

You can also get a list of files in the current folder asynchronously by calling one of the GetFilesAsync methods.

For Windows Server 2012 You must install indexer components to use some CommonFileQuery values because indexer components are not installed by default.

Gets a query result object that contains the files in the current folder and, optionally, in the subfolders of the current folder. The results are based on the specified QueryOptions.

public StorageFileQueryResult CreateFileQueryWithOptions(QueryOptions queryOptions)public StorageFileQueryResult CreateFileQueryWithOptions(QueryOptions queryOptions)Public Function CreateFileQueryWithOptions(queryOptions As QueryOptions) As StorageFileQueryResult

Attributes

ContractVersionAttribute StaticAttribute

Remarks

In the following cases, this query is a shallow query that returns only files in the current folder.

• Default behavior of this method if none of the following options are specified.

• or -

• Specify DefaultQuery as the value of CommonFileQuery when you instantiate the QueryOptions object.

• or -

• Specify Shallow as the value of the FolderDepth property of the QueryOptions object. In the following cases, this query is a deep query that returns files from the current folder and from its subfolders.

• For a library folder, specify a value other than DefaultQuery as the value of CommonFileQuery when you instantiate the QueryOptions object.

• or -

• For any folder, specify Deep as the value of the FolderDepth property of the QueryOptions. > > [!TIP] > Some of the values from the CommonFileQuery enumeration can only be used with a library folder (such as the Pictures library) or the Homegroup folder. In addition to the DefaultQuery option, you can use only the OrderByName and OrderBySearchRank options with a folder that's not a library folder.

For a list of methods that identifies shallow queries and deep queries, see the Remarks in the topic GetFilesAsync.

To check whether the QueryOptions you want to specify are available for the current folder, call the folder's AreQueryOptionsSupported method. To check whether a specific CommonFileQuery is available, call the folder's IsCommonFileQuerySupported method.

You can also get a list of files in the current folder asynchronously by calling one of the GetFilesAsync methods.

To get a query result object that contains the files in the current folder without configuring a QueryOptions object, call one of the CreateFileQuery methods.

To get items that are files or folders, call the CreateItemQueryWithOptions method.

For Windows Server 2012 You must install indexer components to use some QueryOptions because indexer components are not installed by default.

Examples

The following example shows how to get the JPG files in the user's Pictures folder and its subfolders, sorted by date, by calling the CreateFileQueryWithOptions(QueryOptions) method. This query is a deep query because the folder is a library folder and a value other than DefaultQuery from the CommonFileQuery enumeration is specified.

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;

// Set options for file type and sort order.
List<string> fileTypeFilter = new List<string>();
fileTypeFilter.Add(".jpg");
QueryOptions queryOptions = new QueryOptions(CommonFileQuery.OrderByDate, fileTypeFilter);

// Get the JPG files in the user's Pictures folder
// and its subfolders and sort them by date.
StorageFileQueryResult results = picturesFolder.CreateFileQueryWithOptions(queryOptions);

// Iterate over the results and print the list of files
// to the Visual Studio Output window.
IReadOnlyList<StorageFile> sortedFiles = await results.GetFilesAsync();
foreach (StorageFile item in sortedFiles)
{
    Debug.WriteLine(item.Name + ", " + item.DateCreated);
}

// Get the user's Pictures folder.
// Enable the corresponding capability in the app manifest file.
var KnownFolders = Windows.Storage.KnownFolders;
var picturesFolder = KnownFolders.picturesLibrary;

// Set options for file type and sort order.
var fileTypeFilter = [".jpg"];
var CommonFileQuery = Windows.Storage.Search.CommonFileQuery;
var queryOptions = new Windows.Storage.Search.QueryOptions(CommonFileQuery.orderByDate, fileTypeFilter);

// Get the JPG files in the user's Pictures folder
// and its subfolders and sort them by date.
var results = picturesFolder.createFileQueryWithOptions(queryOptions);

// Iterate over the results and print the list of files
// to the Visual Studio Output window.
var sortedFilesPromise = results.getFilesAsync();
sortedFilesPromise.done(function (sortedFiles) {
    sortedFiles.forEach(function forEachFile(item) {
        console.log(item.name, item.dateCreated);
    });
});

//Get the users's pictures folder
//Enable the corresponding cpability in the app manifest file
StorageFolder^ picturesFolder = KnownFolders::PicturesLibrary;

//Set options for file type and sort order
Platform::Collections::Vector<String^>^ fileTypeFilter = ref new Platform::Collections::Vector<String^>();
fileTypeFilter->Append(".jpg");
QueryOptions^ queryOptions = ref new QueryOptions(Windows::Storage::Search::CommonFileQuery::OrderByDate, fileTypeFilter);

//Get the JPG files in the user's pictures folder 
//and its subfolders and sort them by date
StorageFileQueryResult^ results = picturesFolder->CreateFileQueryWithOptions(queryOptions);

create_task(results->GetFilesAsync()).then([=](IVectorView<StorageFile^>^ filesInFolder) 
{
    //Iterate over the results and print the list of files
    // to the visual studio output window
    for (auto it = filesInFolder->First(); it->HasCurrent; it->MoveNext())
    {
             StorageFile^ file = it->Current;
             String^ output = file->Name + "\n";
             OutputDebugString(output->Begin());
    }
    );

See Also

Content indexer sample (Windows 10)

Creates a new subfolder with the specified name in the current folder.

public IAsyncOperation<StorageFolder> CreateFolderAsync(String desiredName)public IAsyncOperation<StorageFolder> CreateFolderAsync(String desiredName)Public Function CreateFolderAsync(desiredName As String) As IAsyncOperation( Of StorageFolder )

Attributes

OverloadAttribute RemoteAsyncAttribute

Remarks

This method uses the FailIfExists value from the CreationCollisionOption enumeration by default. That is, this method raises an exception if a subfolder with the same name already exists in the current folder. If you want to handle a folder name collision in a different way, call the CreateFolderAsync(String, CreationCollisionOption) method.

If you try to create a subfolder in a virtual folder like a library, or a folder that represents a container for a group of files (for example, the return value from some overloads of the GetFoldersAsync method), the CreateFolderAsync method may fail.

Examples

The following example shows how to create a new StorageFolder in the current folder by calling the CreateFolderAsync(String, CreationCollisionOption) overloaded method. This example explicitly specifies a value for options that causes the operation to fail if a folder with the specified desiredName already exists in the current folder.

using Windows.Storage;
using System.Threading.Tasks;

// Get the app's local folder.
StorageFolder localFolder =
    Windows.Storage.ApplicationData.Current.LocalFolder;

// Create a new subfolder in the current folder.
// Raise an exception if the folder already exists.
string desiredName = "Subfolder";
StorageFolder newFolder =
    await localFolder.CreateFolderAsync(desiredName, CreationCollisionOption.FailIfExists);

// Get the app's local folder.
var localFolder = Windows.Storage.ApplicationData.current.localFolder;

// Create a new subfolder in the current folder.
// Raise an exception if the folder already exists.
var desiredName = "Subfolder";
var CreationCollisionOption = Windows.Storage.CreationCollisionOption;
var newFolderPromise = localFolder.createFolderAsync(desiredName, CreationCollisionOption.failIfExists);
newFolderPromise.done(function createFolderSuccess(newFolder) {
    // Subfolder was created in the current folder.

}, function createFolderFail(error) {
    // Subfolder creation fails if the folder already exists. 
});

 //Get apps local folder
 StorageFolder^ localFolder = Windows::Storage::ApplicationData::Current->LocalFolder;

 // Create a new subfolder in the current folder
 // Raise an exception if it already exists
 String^ desiredName = "Subfolder";
 create_task(localFolder->CreateFolderAsync(desiredName,Windows::Storage::CreationCollisionOption::FailIfExists)).then([](StorageFolder^ folder)
 {
    //Do something with folder
 });

Creates a new subfolder with the specified name in the current folder. This method also specifies what to do if a subfolder with the same name already exists in the current folder.

public IAsyncOperation<StorageFolder> CreateFolderAsync(String desiredName, CreationCollisionOption options)public IAsyncOperation<StorageFolder> CreateFolderAsync(String desiredName, CreationCollisionOption options)Public Function CreateFolderAsync(desiredName As String, options As CreationCollisionOption) As IAsyncOperation( Of StorageFolder )

Attributes

OverloadAttribute RemoteAsyncAttribute

Remarks

If a folder with the specified desiredName already exists in the current folder, the specified CreationCollisionOption determines how to handle the collision.

Gets a query result object that contains the subfolders in the current folder.

public StorageFolderQueryResult CreateFolderQuery()public StorageFolderQueryResult CreateFolderQuery()Public Function CreateFolderQuery() As StorageFolderQueryResult

Attributes

OverloadAttribute

Remarks

This query is a shallow query that returns only subfolders in the current folder. For a list of methods that identifies shallow queries and deep queries, see the Remarks in the GetFoldersAsync method.

To specify additional query options, call the CreateFolderQueryWithOptions method.

To get items that are files or folders, call the CreateItemQuery method.

Examples

The following example shows how to get the contents of the subfolders in the user's Pictures folder, grouped into folders by month, by calling the GetFoldersAsync(CommonFolderQuery) overloaded method. (Files from the root of the current folder are not included.)

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 the 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.
StorageFolderQueryResult groupedItems =
    picturesFolder.CreateFolderQuery(CommonFolderQuery.GroupByMonth);

// Iterate over the results and print the list of folders
// and files to the Visual Studio Output window.
foreach (StorageFolder folder in await groupedItems.GetFoldersAsync())
{
    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);
}

// Get the user's Pictures folder.
// Enable the corresponding capability in the app manifest file.
var KnownFolders = Windows.Storage.KnownFolders;
var picturesFolder = KnownFolders.picturesLibrary;

// Get the JPG files in the user's Pictures folder and group them by month.
var CommonFolderQuery = Windows.Storage.Search.CommonFolderQuery;
var groupedItems = picturesFolder.createFolderQuery(CommonFolderQuery.groupByMonth);

// Iterate over the results and print the list of folders
// and files to the Visual Studio Output window.
var subfoldersPromise = groupedItems.getFoldersAsync();
subfoldersPromise.done(function getFoldersSuccess(subfolders) {
    subfolders.forEach(function forEachSubfolder(folder) {
        console.log(folder.name);

        // To iterate over the files in each folder,
        // uncomment the following lines.
        // var filesPromise = folder.getFilesAsync();
        // filesPromise.done(function (files) {
        //     console.log(folder.name);
        //     files.forEach(function forEachFile(file) {
        //         console.log(".", file.name);
        //     });
        // });
    });
});

 // Get user's pictures folder
 StorageFolder^ picturesFolder = KnownFolders::PicturesLibrary;

 // Get the files in the user's Pictures folder and group them by month
 StorageFolderQueryResult^ itemsInFolder = picturesFolder->CreateFolderQuery(CommonFolderQuery::GroupByMonth);

 create_task(itemsInFolder->GetFoldersAsync()).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());
  }
 });

Gets a query result object that contains 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 StorageFolderQueryResult CreateFolderQuery(CommonFolderQuery query)public StorageFolderQueryResult CreateFolderQuery(CommonFolderQuery query)Public Function CreateFolderQuery(query As CommonFolderQuery) As StorageFolderQueryResult

Attributes

OverloadAttribute

Remarks

A CommonFolderQuery groups the contents of subfolders into folders based on specific file attributes (like artist or album) quickly and easily. See the Remarks on the CreateFileQuery method page for more information about specifying DefaultQuery options.

Gets a query result object that contains the subfolders in the current folder and, optionally, nested subfolders. The results are based on the specified QueryOptions.

public StorageFolderQueryResult CreateFolderQueryWithOptions(QueryOptions queryOptions)public StorageFolderQueryResult CreateFolderQueryWithOptions(QueryOptions queryOptions)Public Function CreateFolderQueryWithOptions(queryOptions As QueryOptions) As StorageFolderQueryResult

Attributes

ContractVersionAttribute StaticAttribute

Remarks

For more information and examples on getting query result objects, see CreateFileQueryWithOptions.

Gets a query result object that contains the files and subfolders in the current folder.

public StorageItemQueryResult CreateItemQuery()public StorageItemQueryResult CreateItemQuery()Public Function CreateItemQuery() As StorageItemQueryResult

Attributes

ContractVersionAttribute StaticAttribute

Remarks

This query is a shallow query that returns only items in the current folder. For a list of methods that identifies shallow queries and deep queries, see the Remarks in the topic GetItemsAsync.

You can also get a list of items in the current folder asynchronously by calling one of the GetItemsAsync methods.

To specify additional query options, call the CreateItemQueryWithOptions method.

Examples

The following example shows how to get the files and subfolders in the current folder by calling the CreateItemQuery() method.

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

// Get the app's installation folder.
StorageFolder appFolder = Windows.ApplicationModel.Package.Current.InstalledLocation;

// Get the items in the current folder.
StorageItemQueryResult itemsInFolder = appFolder.CreateItemQuery();

// Iterate over the results and print the list of items
// to the Visual Studio Output window.
foreach (IStorageItem item in await itemsInFolder.GetItemsAsync())
{
    if(item.IsOfType(StorageItemTypes.Folder))
        Debug.WriteLine("Folder: " + item.Name);
    else
        Debug.WriteLine("File: " + item.Name + ", " + item.DateCreated);
}

// Get the app's installation folder.
var appFolder = Windows.ApplicationModel.Package.current.installedLocation;

// Get the items in the current folder.
var itemsInFolder = appFolder.createItemQuery();

// Iterate over the results and print the list of items
// to the Visual Studio Output window.
var itemsPromise = itemsInFolder.getItemsAsync();
itemsPromise.done(function getItemsSuccess(items) {
    items.forEach(function forEachItem(item) {
        var StorageItemTypes = Windows.Storage.StorageItemTypes;
        if (item.isOfType(StorageItemTypes.folder)) {
            console.log("Folder:", item.name);
        } else {
            console.log("File:", item.name, item.dateCreated);
        }
    });
});

// Get the apps installation folder
StorageFolder^ appFolder = Windows::ApplicationModel::Package::Current->InstalledLocation;

StorageItemQueryResult^ results = appFolder->CreateItemQuery();

// Get the items in the current folder; 
create_task(results->GetItemsAsync()).then([=](IVectorView<IStorageItem^>^ itemsInFolder) {

 //Iterate over the results and print the list of items
    // to the visual studio output window
    for (auto it = itemsInFolder->First(); it->HasCurrent; it->MoveNext())
    {
        IStorageItem^ item = it->Current;
        if (item->IsOfType(StorageItemTypes::File))
        {
            String^ output = "File: " + item->Name + "\n";
            OutputDebugString(output->Begin());
        }
        else
        {
            String^ output = "Folder: " + item->Name + "\n";
            OutputDebugString(output->Begin());
        }       
    }
});

Gets a query result object that contains the files and subfolders in the current folder and, optionally, in the subfolders of the current folder. The results are based on the specified QueryOptions.

public StorageItemQueryResult CreateItemQueryWithOptions(QueryOptions queryOptions)public StorageItemQueryResult CreateItemQueryWithOptions(QueryOptions queryOptions)Public Function CreateItemQueryWithOptions(queryOptions As QueryOptions) As StorageItemQueryResult

Attributes

ContractVersionAttribute StaticAttribute

Remarks

For more information and examples on getting query result objects, see CreateFileQueryWithOptions.

Deletes the current folder.

public IAsyncAction DeleteAsync()public IAsyncAction DeleteAsync()Public Function DeleteAsync() As IAsyncAction

Attributes

OverloadAttribute RemoteAsyncAttribute

Remarks

This method implicitly uses StorageDeleteOption.Default to determine whether the item is deleted permanently.

Examples

The following example shows how to delete the current folder by calling the DeleteAsync(StorageDeleteOption) overloaded method. This example explicitly specifies a value for option that deletes the file permanently.

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

// Get the app's local folder.
StorageFolder localFolder = Windows.Storage.ApplicationData.Current.LocalFolder;

// Create a temporary folder in the current folder.
string folderName = "Test";
StorageFolder testFolder = await localFolder.CreateFolderAsync(folderName);

// Has the folder been created?
if(await localFolder.TryGetItemAsync(folderName) != null)
    Debug.WriteLine("Folder " + folderName + " exists.");
else
    Debug.WriteLine("Folder " + folderName + " does not exist.");

// Delete the folder permanently.
await testFolder.DeleteAsync(StorageDeleteOption.PermanentDelete);

// Has the folder been deleted?
if(await localFolder.TryGetItemAsync(folderName) != null)
    Debug.WriteLine("Folder " + folderName + " exists.");
else
    Debug.WriteLine("Folder " + folderName + " does not exist.");

// Get the app's local folder.
var localFolder = Windows.Storage.ApplicationData.current.localFolder;

// Create a temporary folder in the current folder.
var folderName = "Test";
var testFolderPromise = localFolder.createFolderAsync(folderName);
var getItemPromise = testFolderPromise.then(null, function createFolderFail(error) {

    // Folder creation failed.
    // Does the folder already exist?
    return localFolder.tryGetItemAsync(folderName);
});
var deleteItemPromise = getItemPromise.then(function getItemSuccess(testFolder) {
    if (testFolder !== null) {
        console.log("Folder", folderName, " exists.");
    } else {
        console.log("Folder", folderName, " does not exist.");
    }

    // Delete the folder.
    var StorageDeleteOption = Windows.Storage.StorageDeleteOption;
    return testFolder && testFolder.deleteAsync(StorageDeleteOption.permanentDelete);
});
var getDeletedItemPromise = deleteItemPromise.then(function deleteSuccess() {

    // Has the folder been deleted?
    return localFolder.tryGetItemAsync(folderName);
});
getDeletedItemPromise.done(function getDeletedItemSuccess(item) {
    if (item !== null) {
        console.log("Folder", folderName, "exists.");
    } else {
        console.log("Folder", folderName, "does not exist.");
    }
});

StorageFolder^ localFolder = ApplicationData::Current->LocalFolder;

String^ folderName = "test";

create_task(localFolder->CreateFolderAsync(folderName)).then([=](StorageFolder^ newFolder) -> task<IStorageItem^> {
 //Check the folder exists
 return create_task(localFolder->TryGetItemAsync(folderName));
}).then([=](IStorageItem^ newFolder) -> task<void> {
 String^ output = "";
 if (newFolder == nullptr)
 {
  output = "Folder: " + folderName + " not found\n";
 }
 else
 {
  output = "Folder: " + folderName + " created\n";
 }
 OutputDebugString(output->Begin());
 return create_task(newFolder->DeleteAsync(StorageDeleteOption::PermanentDelete));
}).then([=]() -> task<IStorageItem^>  {
 return create_task(localFolder->TryGetItemAsync(folderName));
}).then([=](IStorageItem^ newFolder){
 String^ output = "";
 if (newFolder == nullptr)
 {
  output = "Folder: " + folderName + " deleted\n";
 }
 else
 {
  output = "Folder: " + folderName + " not deleted\n";
 }
 OutputDebugString(output->Begin());
});

Deletes the current folder. This method also specifies whether to delete the folder permanently.

public IAsyncAction DeleteAsync(StorageDeleteOption option)public IAsyncAction DeleteAsync(StorageDeleteOption option)Public Function DeleteAsync(option As StorageDeleteOption) As IAsyncAction

Attributes

OverloadAttribute RemoteAsyncAttribute

Gets the basic properties of the current folder or file group.

public IAsyncOperation<BasicProperties> GetBasicPropertiesAsync()public IAsyncOperation<BasicProperties> GetBasicPropertiesAsync()Public Function GetBasicPropertiesAsync() As IAsyncOperation( Of BasicProperties )

Attributes

RemoteAsyncAttribute

Gets the file with the specified name from the current folder.

public IAsyncOperation<StorageFile> GetFileAsync(String name)public IAsyncOperation<StorageFile> GetFileAsync(String name)Public Function GetFileAsync(name As String) As IAsyncOperation( Of StorageFile )

Attributes

RemoteAsyncAttribute

Remarks

To get an item that's a file or a folder, call the GetItemAsync method.

Examples

The following example shows how to get a file from the current folder by calling the GetFileAsync method. This example also shows how to get a file from a subfolder of the current folder by providing a relative path.

using Windows.Storage;
using System.Threading.Tasks;

// Get the app's installation folder.
StorageFolder appFolder = Windows.ApplicationModel.Package.Current.InstalledLocation;

// Get the app's manifest file from the current folder.
string name = "AppxManifest.xml";
StorageFile manifestFile = await appFolder.GetFileAsync(name);

// Get a file from a subfolder of the current folder
// by providing a relative path.
string image = @"Assets\Logo.scale-100.png";
StorageFile logoImage = await appFolder.GetFileAsync(image);

// Get the app's installation folder.
var appFolder = Windows.ApplicationModel.Package.current.installedLocation;

// Get the app's manifest file from the current folder.
var name = "AppxManifest.xml";
var manifestFilePromise = appFolder.getFileAsync(name);
var logoImagePromise = manifestFilePromise.then(function getFileSuccess(manifestFile) {
    // Get a file from a subfolder of the current folder
    // by providing a relative path.
    var image = "images\\Logo.scale-100.png";
    return appFolder.getFileAsync(image);
});
logoImagePromise.done(function (logoImage) {
    console.log(logoImage.name);
});

// Get the app's installation folder
StorageFolder^ appFolder = Windows::ApplicationModel::Package::Current->InstalledLocation;

// Get the app's manifest file from the current folder
String^ name = "AppxManifest.xml";
create_task(appFolder->GetFileAsync(name)).then([=](StorageFile^ manifest){
 //Do something with the manifest file  
});

Gets the files in the current folder.

public IAsyncOperation<IVectorView<StorageFile>> GetFilesAsync()public IAsyncOperation<IVectorView<StorageFile>> GetFilesAsync()Public Function GetFilesAsync() As IAsyncOperation( Of IVectorViewStorageFile )

Attributes

OverloadAttribute RemoteAsyncAttribute

Remarks

This query is a shallow query that returns only files in the current folder. For a list of methods that identifies shallow queries and deep queries, see the Remarks in the topic GetFilesAsync.

The following table lists methods of the StorageFolder class that get a list of files. The table identifies shallow queries that only return files from the current folder, and deep queries that return files from the current folder and from its subfolders.

Some methods take a value from the CommonFileQuery enumeration. When you specify the DefaultQuery option from the CommonFileQuery enumeration, the query is a shallow query that returns only files in the current folder. When you specify another value from the CommonFileQuery enumeration, the query is a deep query that returns a flattened list of files from the current folder and from its subfolders.

Tip

Some of the values from the CommonFileQuery enumeration can only be used with a library folder (such as the Pictures library) or the Homegroup folder. In addition to the DefaultQuery option, you can use only the OrderByName and OrderBySearchRank options with a folder that's not a library folder.

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

Method	Create a shallow query that only returns files from the current folder	Create a deep query that returns files from the current folder and from its subfolders
GetFilesAsync()	Default behavior of this method.	N/A
GetFilesAsync(CommonFileQuery)	Specify the DefaultQuery option.	For a library folder, specify an option other than DefaultQuery.
GetFilesAsync(CommonFileQuery, UInt32, UInt32)	Specify the DefaultQuery option.	For a library folder, specify an option other than DefaultQuery.
CreateFileQuery()	Default behavior of this method.	N/A
CreateFileQuery(CommonFileQuery)	Specify the DefaultQuery option.	For a library folder, specify an option other than DefaultQuery.
CreateFileQueryWithOptions(QueryOptions)	Default behavior of this method if none of the following options are specified. - or - Specify DefaultQuery as the value of CommonFileQuery 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 CommonFileQuery when you instantiate the QueryOptions object. - or - For any folder, specify Deep as the value of the FolderDepth property of the QueryOptions.

Examples

The following example shows how to get the contents of the user's Pictures folder and its subfolders, sorted by date, by calling the GetFilesAsync(CommonFileQuery, UInt32, UInt32) overloaded method. This example returns a maximum of 20 files, starting with the file at index 0. Since the CommonFileQuery.OrderByDate option sorts dates in descending order (that is, from newest to oldest), this example returns the user's 20 most recent photos.

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 first 20 files in the current folder, sorted by date.
IReadOnlyList<StorageFile> sortedItems = await picturesFolder.GetFilesAsync(CommonFileQuery.OrderByDate,0,20);

// Iterate over the results and print the list of files
// to the Visual Studio Output window.
foreach (StorageFile file in sortedItems)
    Debug.WriteLine(file.Name + ", " + file.DateCreated);

// Get the user's Pictures folder.
// Enable the corresponding capability in the app manifest file.
var KnownFolders = Windows.Storage.KnownFolders;
var picturesFolder = KnownFolders.picturesLibrary;

// Get the first 20 files in the current folder, sorted by date.
var CommonFileQuery = Windows.Storage.Search.CommonFileQuery;
var sortedItemsPromise = picturesFolder.getFilesAsync(CommonFileQuery.orderByDate, 0, 20);
sortedItemsPromise.done(function getFilesSuccess(sortedItems) {

    // Iterate over the results and print the list of files
    // to the Visual Studio Output window.
    sortedItems.forEach(function forEachFile(file) {
        console.log(file.name, file.dateCreated);
    });
});

// Get user's pictures library
StorageFolder^ picturesLibrary = KnownFolders::PicturesLibrary;

// Get the first 20 sorted images in the library
create_task(picturesLibrary->GetFilesAsync(CommonFileQuery::OrderByDate,0,20)).then([=](IVectorView<StorageFile^>^ filesInFolder) {
 //Iterate over the results and print the list of files
 // to the visual studio output window
 for (auto it = filesInFolder->First(); it->HasCurrent; it->MoveNext())
 {
  StorageFile^ file = it->Current;
  String^ output = file->Name + "\n";
  OutputDebugString(output->Begin());
 }
});

Gets the files in the current folder. Also gets the files from the subfolders of the current folder when the value of the query argument is something other than CommonFileQuery.DefaultQuery. Files are sorted based on the specified value from the CommonFileQuery enumeration.

public IAsyncOperation<IVectorView<StorageFile>> GetFilesAsync(CommonFileQuery query)public IAsyncOperation<IVectorView<StorageFile>> GetFilesAsync(CommonFileQuery query)Public Function GetFilesAsync(query As CommonFileQuery) As IAsyncOperation( Of IVectorViewStorageFile )

Attributes

OverloadAttribute RemoteAsyncAttribute

Gets an index-based range of files from the list of all files in the current folder. Also gets the files from the subfolders of the current folder when the value of the query argument is something other than CommonFileQuery.DefaultQuery. Files are sorted based on the specified value from the CommonFileQuery enumeration.

public IAsyncOperation<IVectorView<StorageFile>> GetFilesAsync(CommonFileQuery query, UInt32 startIndex, UInt32 maxItemsToRetrieve)public IAsyncOperation<IVectorView<StorageFile>> GetFilesAsync(CommonFileQuery query, UInt32 startIndex, UInt32 maxItemsToRetrieve)Public Function GetFilesAsync(query As CommonFileQuery, startIndex As UInt32, maxItemsToRetrieve As UInt32) As IAsyncOperation( Of IVectorViewStorageFile )

Attributes

OverloadAttribute RemoteAsyncAttribute

Gets the subfolder with the specified name from the current folder.

public IAsyncOperation<StorageFolder> GetFolderAsync(String name)public IAsyncOperation<StorageFolder> GetFolderAsync(String name)Public Function GetFolderAsync(name As String) As IAsyncOperation( Of StorageFolder )

Attributes

RemoteAsyncAttribute

Remarks

Examples

The following example shows how to get a subfolder from the current folder by calling the GetFolderAsync method. This example also shows how to get a subfolder from a subfolder of the current folder by providing a relative path.

using Windows.Storage;
using System.Threading.Tasks;

// Get the app's local folder.
StorageFolder localFolder = ApplicationData.Current.LocalFolder;

// Create 2 levels of subfolders in the app's local folder.
string name1 = "Subfolder1";
StorageFolder subFolder1 = await localFolder.CreateFolderAsync(name1);
string name2 = "Subfolder2";
StorageFolder subFolder2 = await subFolder1.CreateFolderAsync(name2);

// Get the subfolder of the app's local folder.
string level1FolderName = "Subfolder1";
StorageFolder level1Folder = await localFolder.GetFolderAsync(level1FolderName);

// Get the subfolder of the subfolder by providing a relative path.
string level2FolderName = @"Subfolder1\Subfolder2";
StorageFolder level2Folder = await localFolder.GetFolderAsync(level2FolderName);

// Get the app's local folder.
var localFolder = Windows.Storage.ApplicationData.current.localFolder;

// Create 2 levels of subfolders in the app's local folder.
var name1 = "Subfolder1";
var subFolder1Promise = localFolder.createFolderAsync(name1);
var subFolder2Promise = subFolder1Promise.then(function createFolder1Success(subFolder1) {
    var name2 = "Subfolder2";
    return subFolder1.createFolderAsync(name2);
});
var level1FolderPromise = subFolder1Promise.then(function createFolder1Success(subFolder1) {
    // Get the subfolder of the app's local folder.
    var level1FolderName = "Subfolder1";
    return localFolder.getFolderAsync(level1FolderName);
});
level1FolderPromise.done(function (level1Folder) {
});
var level2FolderPromise = subFolder2Promise.then(function createFolder2Success(subFolder2) {
    // Get the subfolder of the subfolder
    // by providing a relative path.
    var level2FolderName = "Subfolder1\\Subfolder2";
    return localFolder.getFolderAsync(level2FolderName);
});
level2FolderPromise.done(function getFolderSuccess(level2Folder) {
});

// Get the app's local folder
StorageFolder^ localFolder = ApplicationData::Current->LocalFolder;

// Create 2 levels of subfolders in the app's local folder.
String^ name1 = "Subfolder1";
String^ name2 = "Subfolder2";
String^ level2FolderName = "Subfolder1\\Subfolder2";

create_task(localFolder->CreateFolderAsync(name1)).then([=](StorageFolder^ subFolder1) -> task <StorageFolder^> {
 return create_task(subFolder1->CreateFolderAsync(name2));
}).then([=](StorageFolder^ subFolder2) -> task<StorageFolder^> {
 // Get the subfolder of the subfolder
 // by providing a relative path.
 return create_task(localFolder->GetFolderAsync(level2FolderName));
});

Gets the folder that has the specified absolute path in the file system.

public static IAsyncOperation<StorageFolder> GetFolderFromPathAsync(String path)public static IAsyncOperation<StorageFolder> GetFolderFromPathAsync(String path)Public Static Function GetFolderFromPathAsync(path As String) As IAsyncOperation( Of StorageFolder )

Attributes

RemoteAsyncAttribute

Remarks

Examples

The following example shows how to get the folder that has the specified absolute path in the file system by calling the GetFolderFromPathAsync method.

using Windows.Storage;
using System.Threading.Tasks;

// Get the path to the app's Assets folder.
string root = Windows.ApplicationModel.Package.Current.InstalledLocation.Path;
string path = root + @"\Assets";

// Get the folder object that corresponds to this absolute path in the file system.
StorageFolder folder = await StorageFolder.GetFolderFromPathAsync(path);

// Get the path to the app's Assets folder.
var root = Windows.ApplicationModel.Package.current.installedLocation.path;
var path = root + "\\Assets";

// Get the folder object that corresponds to
// this absolute path in the file system.
var StorageFolder = Windows.Storage.StorageFolder;
var folderPromise = StorageFolder.getFolderFromPathAsync(path);
folderPromise.done(function getFolderSuccess(folder) {
});

// Get the path to the app's Assets folder.
String^ root = Windows::ApplicationModel::Package::Current->InstalledLocation->Path;

// Get the folder object that corresponds to
// this absolute path in the file system.
create_task(StorageFolder::GetFolderFromPathAsync(root)).then([=](StorageFolder^ folder){
 String^ output = folder->Name;
 OutputDebugString(output->Begin());
});

Gets the subfolders in the current folder.

public IAsyncOperation<IVectorView<StorageFolder>> GetFoldersAsync()public IAsyncOperation<IVectorView<StorageFolder>> GetFoldersAsync()Public Function GetFoldersAsync() As IAsyncOperation( Of IVectorViewStorageFolder )

Attributes

OverloadAttribute RemoteAsyncAttribute

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.

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

// Get the user's Pictures folder.
// Enable the corresponding capability in the app manifest file.
var KnownFolders = Windows.Storage.KnownFolders;
var picturesFolder = KnownFolders.picturesLibrary;

// Get the files in the user's Pictures folder, grouped by month.
// Get only the first 4 folders (months).
var CommonFolderQuery = Windows.Storage.Search.CommonFolderQuery;
var groupedItemsPromise = picturesFolder.getFoldersAsync(CommonFolderQuery.groupByMonth, 0, 4);
groupedItemsPromise.done(function getFoldersSuccess(groupedItems) {

    // Iterate over the results and print the list of folders
    // and files to the Visual Studio Output window.
    groupedItems.forEach(function forEachFolder(folder) {
        console.log(folder.name);

        // To iterate over the files in each folder,
        // uncomment the following lines.
        // var getFilesPromise = folder.getFilesAsync();
        // getFilesPromise.done(function getFilesSuccess(files) {
        //     console.log(folder.name);
        //     files.forEach(function forEachFile(file) {
        //         console.log(".", file.name);
        //     });
        // });
    });
});

// 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)).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());
 }
});

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 IAsyncOperation<IVectorView<StorageFolder>> GetFoldersAsync(CommonFolderQuery query)public IAsyncOperation<IVectorView<StorageFolder>> GetFoldersAsync(CommonFolderQuery query)Public Function GetFoldersAsync(query As CommonFolderQuery) As IAsyncOperation( Of IVectorViewStorageFolder )

Attributes

OverloadAttribute RemoteAsyncAttribute

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 IAsyncOperation<IVectorView<StorageFolder>> GetFoldersAsync(CommonFolderQuery query, UInt32 startIndex, UInt32 maxItemsToRetrieve)public IAsyncOperation<IVectorView<StorageFolder>> GetFoldersAsync(CommonFolderQuery query, UInt32 startIndex, UInt32 maxItemsToRetrieve)Public Function GetFoldersAsync(query As CommonFolderQuery, startIndex As UInt32, maxItemsToRetrieve As UInt32) As IAsyncOperation( Of IVectorViewStorageFolder )

Attributes

OverloadAttribute RemoteAsyncAttribute

Gets the indexed state of the current folder.

public IAsyncOperation<IndexedState> GetIndexedStateAsync()public IAsyncOperation<IndexedState> GetIndexedStateAsync()Public Function GetIndexedStateAsync() As IAsyncOperation( Of IndexedState )

Attributes

RemoteAsyncAttribute

Gets the file or folder with the specified name from the current folder.

public IAsyncOperation<IStorageItem> GetItemAsync(String name)public IAsyncOperation<IStorageItem> GetItemAsync(String name)Public Function GetItemAsync(name As String) As IAsyncOperation( Of IStorageItem )

Attributes

RemoteAsyncAttribute

Remarks

Call the IsOfType method of the IStorageItem interface to determine whether the returned item is a file or a folder.

To get a specific file without casting the return value, call the GetFileAsync method. To get a specific folder without casting the return value, call the GetFolderAsync method.

To try to get a file or folder by name, or to check whether a file or folder exists, without the need to handle a FileNotFoundException, call the TryGetItemAsync method.

Examples

The following example shows how to get a single file or folder from the current folder by calling the GetItemAsync method. This example also shows how to get an item from a subfolder of the current folder by providing a relative path.

using Windows.Storage;
using System.Threading.Tasks;

// Get the app's installation folder.
StorageFolder appFolder = Windows.ApplicationModel.Package.Current.InstalledLocation;

// Get the app's manifest file.
string name = "AppxManifest.xml";
StorageFile manifestFile = (StorageFile)await appFolder.GetItemAsync(name);

// Get a file from a subfolder of the current folder
// by providing a relative path.
string image = @"Assets\Logo.scale-100.png";
StorageFile logoImage = (StorageFile)await appFolder.GetItemAsync(image);

// Get the app's installation folder.
var appFolder = Windows.ApplicationModel.Package.current.installedLocation;

// Get the app's manifest file.
var name = "AppxManifest.xml";
var manifestFilePromise = appFolder.getItemAsync(name);
manifestFilePromise.done(function getItemSuccess(manifestFile) {
});

// Get a file from a subfolder of the current folder
// by providing a relative path.
var image = "Assets\\Logo.scale-100.png";
var logoImagePromise = appFolder.getItemAsync(image);
logoImagePromise.done(function getItemSuccess(logoImage) {
});

// Get the app's installation folder
StorageFolder^ appFolder = Windows::ApplicationModel::Package::Current->InstalledLocation;

// Get the app's manifest file from the current folder
String^ name = "AppxManifest.xml";
create_task(appFolder->GetItemAsync(name)).then([=](IStorageItem^ manifest){
  //Do something with the manifest file  
});

Gets the files and subfolders in the current folder.

public IAsyncOperation<IVectorView<IStorageItem>> GetItemsAsync()public IAsyncOperation<IVectorView<IStorageItem>> GetItemsAsync()Public Function GetItemsAsync() As IAsyncOperation( Of IVectorViewIStorageItem )

Attributes

OverloadAttribute RemoteAsyncAttribute

Remarks

The following table lists methods of the StorageFolder class that get a list of files and folders. The table identifies shallow queries that only return items from the current folder, and deep queries that return items from the current folder and from its subfolders.

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

Method	Create a shallow query that only returns items from the current folder	Create a deep query that returns items from the current folder and from its subfolders
GetItemsAsync()	Default behavior of this method.	N/A
GetItemsAsync(UInt32, UInt32)	Default behavior of this method.	N/A
CreateItemQuery()	Default behavior of this method.	N/A
CreateItemQueryWithOptions(QueryOptions)	Default behavior of this method if none of the following options are specified. - or - Specify DefaultQuery as the value of CommonFileQuery or 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 CommonFileQuery or CommonFolderQuery when you instantiate the QueryOptions object. - or - For any folder, specify Deep as the value of the FolderDepth property of the QueryOptions.

To get only files, call the GetFilesAsync method. To get only folders, call the GetFoldersAsync method.

Examples

The following example shows how to get the files and subfolders in the current folder by calling the GetItemsAsync() method.

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

// Get the app's installation folder.
StorageFolder appFolder = Windows.ApplicationModel.Package.Current.InstalledLocation;

// Get the files and folders in the current folder.
IReadOnlyList<IStorageItem> itemsInFolder = await appFolder.GetItemsAsync();

// Iterate over the results and print the list of items
// to the Visual Studio Output window.
foreach (IStorageItem item in itemsInFolder)
{
    if(item.IsOfType(StorageItemTypes.Folder))
        Debug.WriteLine("Folder: " + item.Name);
    else
        Debug.WriteLine("File: " + item.Name + ", " + item.DateCreated);
}

// Get the app's installation folder.
var appFolder = Windows.ApplicationModel.Package.current.installedLocation;

// Get the files and folders in the current folder.
var itemsInFolderPromise = appFolder.getItemsAsync();

// Iterate over the results and print the list of items
// to the Visual Studio Output window.
itemsInFolderPromise.done(function getItemsSuccess(itemsInFolder) {
    itemsInFolder.forEach(function forEachItem(item) {
        var StorageItemTypes = Windows.Storage.StorageItemTypes;
        if (item.isOfType(StorageItemTypes.folder)) {
            console.log("Folder:", item.name);
        } else {
            console.log("File:", item.name, item.dateCreated);
        }
    })
});

// Get the apps installation folder
StorageFolder^ appFolder = Windows::ApplicationModel::Package::Current->InstalledLocation;

// Get the items in the current folder; 
create_task(appFolder->GetItemsAsync()).then([=](IVectorView<IStorageItem^>^ itemsInFolder) {

 //Iterate over the results and print the list of items
 // to the visual studio output window
 for (auto it = itemsInFolder->First(); it->HasCurrent; it->MoveNext())
 {
  IStorageItem^ item = it->Current;
  if (item->IsOfType(StorageItemTypes::File))
  {
   String^ output = "File: " + item->Name + "\n";
   OutputDebugString(output->Begin());
  }
  else
  {
   String^ output = "Folder: " + item->Name + "\n";
   OutputDebugString(output->Begin());
  }
 }
});

Gets an index-based range of files and folders from the list of all files and subfolders in the current folder.

public IAsyncOperation<IVectorView<IStorageItem>> GetItemsAsync(UInt32 startIndex, UInt32 maxItemsToRetrieve)public IAsyncOperation<IVectorView<IStorageItem>> GetItemsAsync(UInt32 startIndex, UInt32 maxItemsToRetrieve)Public Function GetItemsAsync(startIndex As UInt32, maxItemsToRetrieve As UInt32) As IAsyncOperation( Of IVectorViewIStorageItem )

Attributes

OverloadAttribute RemoteAsyncAttribute

Gets the parent folder of the current folder.

public IAsyncOperation<StorageFolder> GetParentAsync()public IAsyncOperation<StorageFolder> GetParentAsync()Public Function GetParentAsync() As IAsyncOperation( Of StorageFolder )

Attributes

RemoteAsyncAttribute

Gets a scaled image as a thumbnail, determined by the purpose of the thumbnail.

public IAsyncOperation<StorageItemThumbnail> GetScaledImageAsThumbnailAsync(ThumbnailMode mode)public IAsyncOperation<StorageItemThumbnail> GetScaledImageAsThumbnailAsync(ThumbnailMode mode)Public Function GetScaledImageAsThumbnailAsync(mode As ThumbnailMode) As IAsyncOperation( Of StorageItemThumbnail )

Attributes

OverloadAttribute RemoteAsyncAttribute

Gets a scaled image as a thumbnail, determined by the purpose of the thumbnail and the requested size.

public IAsyncOperation<StorageItemThumbnail> GetScaledImageAsThumbnailAsync(ThumbnailMode mode, UInt32 requestedSize)public IAsyncOperation<StorageItemThumbnail> GetScaledImageAsThumbnailAsync(ThumbnailMode mode, UInt32 requestedSize)Public Function GetScaledImageAsThumbnailAsync(mode As ThumbnailMode, requestedSize As UInt32) As IAsyncOperation( Of StorageItemThumbnail )

Attributes

OverloadAttribute RemoteAsyncAttribute

Gets a scaled image as a thumbnail, determined by the purpose of the thumbnail, the requested size, and the specified options

public IAsyncOperation<StorageItemThumbnail> GetScaledImageAsThumbnailAsync(ThumbnailMode mode, UInt32 requestedSize, ThumbnailOptions options)public IAsyncOperation<StorageItemThumbnail> GetScaledImageAsThumbnailAsync(ThumbnailMode mode, UInt32 requestedSize, ThumbnailOptions options)Public Function GetScaledImageAsThumbnailAsync(mode As ThumbnailMode, requestedSize As UInt32, options As ThumbnailOptions) As IAsyncOperation( Of StorageItemThumbnail )

Attributes

OverloadAttribute RemoteAsyncAttribute

Gets a thumbnail image for the current folder, sized for the specified purpose of the thumbnail.

public IAsyncOperation<StorageItemThumbnail> GetThumbnailAsync(ThumbnailMode mode)public IAsyncOperation<StorageItemThumbnail> GetThumbnailAsync(ThumbnailMode mode)Public Function GetThumbnailAsync(mode As ThumbnailMode) As IAsyncOperation( Of StorageItemThumbnail )

Attributes

OverloadAttribute RemoteAsyncAttribute

Remarks

For a sample that demonstrates the GetThumbnailAsync method, see File and folder thumbnail sample.

For guidance about choosing the best thumbnail mode, see Guidelines and checklist for thumbnails.

The StorageFolder.GetThumbnailAsync method sometimes returns the default image of a folder. For Windows Phone Store app, this method ignores the current theme when it returns this default image. The image returned is always the image for the dark theme; that is, the folder is transparent with a white border. If you want to return the image for the light theme, you have to create your own image that's visible on a light background. Then you have to use conditional logic to check the active theme. If the active theme is the light theme, use a method other than GetThumbnailAsync to retrieve your custom image.

Examples

The following example gets a thumbnail image for the user's Pictures folder and displays the thumbnail in an Image control. This example also requests an image whose longest side is 64 pixels, and requests the image only if it's already cached on the device. The example assumes that there's an Image control named ImageControl on the current page.

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

using Windows.Storage;
using Windows.Storage.FileProperties;
using System.Threading.Tasks;
using Windows.UI.Xaml.Media.Imaging; // For the Bitmap object.

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

// Get a thumbnail for the current folder.
StorageItemThumbnail thumb =
    await picturesFolder.GetThumbnailAsync(ThumbnailMode.SingleItem,
    64, ThumbnailOptions.ReturnOnlyIfCached);

// Display the thumbnail in an Image control
// named ImageControl on the current page.
BitmapImage bitmapImage = new BitmapImage();
bitmapImage.SetSource(thumb);
ImageControl.Source = bitmapImage;

Gets a thumbnail image for the current folder, sized for the specified purpose of the thumbnail and adjusted to the requested size.

public IAsyncOperation<StorageItemThumbnail> GetThumbnailAsync(ThumbnailMode mode, UInt32 requestedSize)public IAsyncOperation<StorageItemThumbnail> GetThumbnailAsync(ThumbnailMode mode, UInt32 requestedSize)Public Function GetThumbnailAsync(mode As ThumbnailMode, requestedSize As UInt32) As IAsyncOperation( Of StorageItemThumbnail )

Attributes

OverloadAttribute RemoteAsyncAttribute

Gets a thumbnail image for the current folder, sized for the specified purpose of the thumbnail and adjusted to the requested size with the specified options.

public IAsyncOperation<StorageItemThumbnail> GetThumbnailAsync(ThumbnailMode mode, UInt32 requestedSize, ThumbnailOptions options)public IAsyncOperation<StorageItemThumbnail> GetThumbnailAsync(ThumbnailMode mode, UInt32 requestedSize, ThumbnailOptions options)Public Function GetThumbnailAsync(mode As ThumbnailMode, requestedSize As UInt32, options As ThumbnailOptions) As IAsyncOperation( Of StorageItemThumbnail )

Attributes

OverloadAttribute RemoteAsyncAttribute

Indicates whether the current folder supports the specified CommonFileQuery.

public PlatForm::Boolean IsCommonFileQuerySupported(CommonFileQuery query)public bool IsCommonFileQuerySupported(CommonFileQuery query)Public Function IsCommonFileQuerySupported(query As CommonFileQuery) As bool

Attributes

ContractVersionAttribute StaticAttribute

Indicates whether the current folder supports the specified CommonFolderQuery.

public PlatForm::Boolean IsCommonFolderQuerySupported(CommonFolderQuery query)public bool IsCommonFolderQuerySupported(CommonFolderQuery query)Public Function IsCommonFolderQuerySupported(query As CommonFolderQuery) As bool

Attributes

ContractVersionAttribute StaticAttribute

Indicates whether the current folder is equal to the specified folder.

public PlatForm::Boolean IsEqual(IStorageItem item)public bool IsEqual(IStorageItem item)Public Function IsEqual(item As IStorageItem) As bool

Attributes

ContractVersionAttribute StaticAttribute

Remarks

Use the IsEqual method to determine whether two items represent the same folder.

This method compares the Path property of both items to determine if they are the same. If there is no Path (if the item is a library for example), or if the paths do not match the items are compared using IShellItem::Compare.

Indicates whether the current StorageFolder matches the specified StorageItemTypes value.

public PlatForm::Boolean IsOfType(StorageItemTypes type)public bool IsOfType(StorageItemTypes type)Public Function IsOfType(type As StorageItemTypes) As bool

Attributes

ContractVersionAttribute StaticAttribute

Renames the current folder.

public IAsyncAction RenameAsync(String desiredName)public IAsyncAction RenameAsync(String desiredName)Public Function RenameAsync(desiredName As String) As IAsyncAction

Attributes

OverloadAttribute RemoteAsyncAttribute

Remarks

If the name you specify is invalid, this method (and its overload) throws an exception. To handle all the ways the specified name could be invalid, you must catch all four of these exceptions:

E_INVALIDARG

E_FAIL

ERROR_FILENAME_EXCED_RANGE

ERROR_INVALID_NAME

If the file is deleted before the rename finishes, this method throws the ERROR_FILE_NOT_FOUND exception. You must also catch and handle this exception when you use this method.

Renames the current folder and specifies what to do if a folder with the same name already exists.

public IAsyncAction RenameAsync(String desiredName, NameCollisionOption option)public IAsyncAction RenameAsync(String desiredName, NameCollisionOption option)Public Function RenameAsync(desiredName As String, option As NameCollisionOption) As IAsyncAction

Attributes

OverloadAttribute RemoteAsyncAttribute

Tries to get the file or folder with the specified name from the current folder. Returns null instead of raising a FileNotFoundException if the specified file or folder is not found.

public IAsyncOperation<IStorageItem> TryGetItemAsync(String name)public IAsyncOperation<IStorageItem> TryGetItemAsync(String name)Public Function TryGetItemAsync(name As String) As IAsyncOperation( Of IStorageItem )

Attributes

RemoteAsyncAttribute

Remarks

Call the TryGetItemAsync method to try to get a file or folder by name, or to check whether a file or folder exists, without the need to handle a FileNotFoundException. If the file or folder can't be found, TryGetItemAsync returns null instead of raising an exception.

Call the IsOfType method of the IStorageItem interface to determine whether the returned item is a file or a folder.

Examples

The following example shows how to try to get a single file or folder from the current folder, or to check whether the file or folder exists, by calling the TryGetItemAsync method.

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

// Get the path to the app's Assets folder.
string root = Windows.ApplicationModel.Package.Current.InstalledLocation.Path;
string path = root + @"\Assets";

// Get the app's Assets folder.
StorageFolder assetsFolder = await StorageFolder.GetFolderFromPathAsync(path);

// Check whether an image with the specified scale exists.
string imageName = "Logo.scale-140.png";
if (await assetsFolder.TryGetItemAsync(imageName) != null)
    Debug.WriteLine(imageName + " exists.");
else  // Return value of TryGetItemAsync is null.
    Debug.WriteLine(imageName + " does not exist.");

This example shows how to check for the existence of a file.

function getFile() {
        var outputDiv = document.getElementById("output");
        Windows.Storage.KnownFolders.picturesLibrary.tryGetItemAsync("sample.dat").done(function (file) {
            if (file !== null) {
                outputDiv.innerHTML = "Operation result: " + file.name;
            } else {
                outputDiv.innerHTML = "Operation result: null";
            }
        });
    }

// Get the path to the app's Assets folder.
var root = Windows.ApplicationModel.Package.current.installedLocation.path;
var path = root + "\\Assets";

// Get the app's Assets folder.
var assetsFolderPromise = StorageFolder.getFolderFromPathAsync(path);

// Check whether an image with the specified scale exists.
var imageName = "Logo.scale-140.png";
var getImagePromise = assetsFolderPromise.then(function getFolderSuccess(assetsFolder) {
    return assetsFolder.tryGetItemAsync(imageName);
});
getImagePromise.done(function getItemSuccess(image) {
    if (image !== null) {
        console.log(imageName, "exists.");
    } else {
        console.log(imageName, "does not exist.")
    }
});

String^ imageName = "Logo.scale-140.png";
// Get the app'ss Assets folder
String^ path = Windows::ApplicationModel::Package::Current->InstalledLocation->Path + "\\Assets";

create_task(StorageFolder::GetFolderFromPathAsync(path)).then([=](StorageFolder^ assets) -> task < IStorageItem^ > 
{
 return create_task(assets->TryGetItemAsync(imageName));
}).then([=](IStorageItem^ image) {
 String^ output = "";
 if (image == nullptr)
 {
  output = "File not found\n";
 }
 else
 {
  //output = "File: " + image->Name + " found \n";
 }
 OutputDebugString(output->Begin());
});