Definition

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

Note that when you call a file picker to let the user pick a folder, the file picker returns the folder as a StorageFolder.

There is not currently a "MoveAsync" or similar method. One simple implementation of moving a folder might be to get the desired folder, copy it to the desired location, and then delete the original folder.

The date and time that the current folder was created as type DateTime.

For example: Fri Sep 16 13:47:08 PDT 2011.

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

winrt::hstring FolderRelativeId();

public string FolderRelativeId { get; }

Public ReadOnly Property FolderRelativeId As string

var string = storageFolder.folderRelativeId;

Value

stringstringstring

The identifier for the current folder or file group within a query result or StorageFolder.

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.

True if the folder or file group supports the specified QueryOptions; otherwise false.

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.

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:

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

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.

A query result object. Call the GetFilesAsync method of the query result to get the flat list of files. This method returns a list of type IReadOnlyList&lt;StorageFile >. Each file is represented by an item of type StorageFile.

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

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.

A query result object. Call the GetFilesAsync method of the query result to get the flat list of files, sorted as specified by query. This method returns a list of type IReadOnlyList&lt;StorageFile >. Each file is represented by an item of type StorageFile.

Exceptions

ArgumentExceptionArgumentExceptionArgumentException

You specified a value other than DefaultQuery from the CommonFileQuery enumeration for a folder that's not a library folder. Check the value of query.

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.

A query result object that contains the files in the current folder and, optionally, in the subfolders of the current folder, filtered and sorted based on the specified QueryOptions. Call the GetFilesAsync method of the query result to get the flat list of files, sorted as specified by queryOptions. This method returns a list of type IReadOnlyList&lt;StorageFile >. Each file is represented by an item of type StorageFile.

Exceptions

ArgumentExceptionArgumentExceptionArgumentException

You specified a value other than DefaultQuery from the CommonFileQuery enumeration for a folder that's not a library folder. Check the value of query.

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.

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.

You don't have permission to create a subfolder in the current folder.

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

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.

A query result object. Call the GetFoldersAsync method of the query result to get the subfolders in the current folder. This method returns a list of type IReadOnlyList&lt;StorageFolder >. Each file or folder is represented by an item of type StorageFolder.

You don't have permission to access the contents of the current folder.

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

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.

A query result object. Call the GetFoldersAsync method of the query result to get the subfolders in the current folder. When the value of the query argument is something other than CommonFolderQuery.DefaultQuery, the query result object contains 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&lt;StorageFolder >. Each folder in the list is represented by a StorageFolder object.

You don't have permission to access the contents of the current folder.

ArgumentExceptionArgumentExceptionArgumentException

You specified a value other than DefaultQuery from the CommonFolderQuery enumeration for a folder that's not a library folder. Check the value of query.

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.

A query result object. Call the GetFoldersAsync method of the query result to get the subfolders in the current folder. If you provided a CommonFolderQuery value other than CommonFolderQuery.DefaultQuery when you instantiated the QueryOptions, the query result object contains 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 queryOptions. The list is of type IReadOnlyList&lt;StorageFolder >. Each folder in the list is represented by a StorageFolder object.

A query result object. Call the GetItemsAsync method of the query result to get the files and subfolders in the current folder. This method returns a list of type IReadOnlyList&lt;IStorageItem >. Each file or folder is represented by an item of type IStorageItem.

A query result object. Call the GetItemsAsync method of the query result to get the files and subfolders in the current folder and, optionally, in the subfolders of the current folder, filtered and sorted based on the specified QueryOptions. This method returns a list of type IReadOnlyList&lt;IStorageItem >. Each file or folder is represented by an item of type IStorageItem.

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.

The path cannot be in Uri format (for example, /image.jpg). Check the value of name.

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

When this method completes successfully, it returns a list of the files in the current folder. The list is of type IReadOnlyList&lt;StorageFile >. Each file in the list is represented by a StorageFile object.

You don't have permission to access the contents of the current folder.

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

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.

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.

When this method completes successfully, it returns a flat list of files, sorted as specified by query. The list is of type IReadOnlyList&lt;StorageFile >. Each file in the list is represented by a StorageFile object.

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.

When this method completes successfully, it returns a flat list of files sorted as specified by query. The list is of type IReadOnlyList&lt;StorageFile >. Each file in the list is represented by a StorageFile object.

The path cannot be in Uri format (for example, /Assets). Check the value of name.

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.

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

You don't have permission to access the contents of the current folder.

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

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.

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.

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.

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&lt;StorageFolder >. Each folder in the list is represented by a StorageFolder object.

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.

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&lt;StorageFolder >. Each folder in the list is represented by a StorageFolder object.

The path cannot be in Uri format (for example, /image.jpg). Check the value of name.

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.

When this method completes successfully, it returns a list of the files and folders in the current folder. The list is of type IReadOnlyList&lt;IStorageItem >. Each item in the list is represented by an IStorageItem object.

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.

When this method completes successfully, it returns a list of the files and subfolders in the current folder. The list is of type IReadOnlyList&lt;IStorageItem >. Each item in the list is represented by an IStorageItem object.

The requested size, in pixels, of the longest edge of the thumbnail. Windows uses the requestedSize as a guide and tries to scale the thumbnail image without reducing the quality of the image.

If Windows can't find a thumbnail image that it can scale to meet the requested size, a larger thumbnail might be returned. If no larger thumbnail is available, a thumbnail image that is smaller than the requested size might be returned.

The requested size, in pixels, of the longest edge of the thumbnail. Windows uses the requestedSize as a guide and tries to scale the thumbnail image without reducing the quality of the image.

If Windows can't find a thumbnail image that it can scale to meet the requested size, a larger thumbnail might be returned. If no larger thumbnail is available, a thumbnail image that is smaller than the requested size might be returned.

The enum value that describes the desired behavior to use to retrieve the thumbnail image. The specified behavior might affect the size and/or quality of the image and how quickly the thumbnail image is retrieved.

When this method completes successfully, it returns a StorageItemThumbnail that represents the thumbnail image, or null if there is no thumbnail image associated with the folder.

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;

Remarks

The StorageFolder.GetThumbnailAsync method sometimes returns the default image of a folder. For Windows Phone 8.x 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.

The requested size, in pixels, of the longest edge of the thumbnail. This method uses the requestedSize as a guide and tries to scale the thumbnail image without reducing the quality of the image.

If this method can't find a thumbnail image that it can scale to the requested size, it may return a larger thumbnail. If no larger thumbnail is available, it may return a thumbnail image that is smaller than the requested size.

The requested size, in pixels, of the longest edge of the thumbnail. This method uses the requestedSize as a guide and tries to scale the thumbnail image without reducing the quality of the image.

If this method can't find a thumbnail image that it can scale to the requested size, it may return a larger thumbnail. If no larger thumbnail is available, it may return a thumbnail image that is smaller than the requested size.

The IStorageItem object that represents the folder to compare against.

Returns

boolboolbool

Returns true if the current folder is equal to the specified folder; otherwise false.

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.

When this method completes successfully, it returns an IStorageItem that represents the specified file or folder. If the specified file or folder is not found, this method returns null instead of raising an exception.

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.