Quickstart: Accessing files programmatically (HTML)

Article
10/13/2015

[This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation]

Access files and folders that are in a location like a folder, library, device, or network location. You can also query the files and folders in a location by constructing file and folder queries.

Prerequisites

Understand async programming for Windows Runtime apps using JavaScript

You can learn how to write asynchronous apps in Quickstart: Using promises in JavaScript.
Access permissions to the location

For example, the code in these examples require the Pictures library capability, but your location may require a different capability or no capability at all. To learn more, see File access and permissions. To learn about how to use the file picker to access files and folders, see Quickstart: accessing files with file pickers.

Enumerate the top-level files and folders in a location

Get a StorageFolder that represents the location.

If you want to get a list of the contents of a particular folder, you must first get a StorageFolder object that represents that location.

The Folder enumeration sample demonstrates how to get the Pictures library:
```
var picturesLibrary = Windows.Storage.KnownFolders.picturesLibrary;
```
In the previous example, we use KnownFolders to get the Pictures library (as a StorageFolder object). You can use KnownFolders properties to get folders that represent a number of user resources such as libraries, devices, or network locations.

Important If you want to use a KnownFolders property to access a library, device, or network location your app must have the corresponding capability in its app manifest. To learn more about file access and capabilities, see File access and permissions and Access to user resources using the Windows Runtime.
Get a list of folder contents.

The Folder enumeration sample demonstrates how to get a list of items in the Pictures library:
```
picturesLibrary.getItemsAsync().then(function (items) {
```
As shown in the previous example, you can call getItemsAsync() to get a list of all the contents of the folder (a StorageFolder object). If you don't want all of the items, you can call getItemsAsync(startIndex, maxItemsToRetrieve) to get folder contents in a range by index.

When you call a getItemsAsync method on a folder, the list of items to receive is limited to the files and sub-folders in that folder and does not include any files and folders contained in those sub-folders.

If you want a list of the files in a folder, you can call a getFilesAsync method. If you want a list of folders, you can call a getFoldersAsync method.

Use then after your get operation to define a function that takes the list of objects that you receive, items in the previous example, and performs the additional tasks you need.
Working with your list.

The Folder enumeration sample demonstrates how to perform additional tasks with the list of items in the Pictures library:
```
    outputHeader(picturesLibrary.name, items.size);
    items.forEach(function (item) { 
        if (item.isOfType(Windows.Storage.StorageItemTypes.folder)) { 
            output(id(picturesLibrary.name), item.name + "\\"); 
        } 
        else { 
            output(id(picturesLibrary.name), item.fileName); 
        } 
    });
```
The previous example passes the name of the folder and the size of the list to a helper function that displays this information to the user.

You can also iterate through the list of items to perform additional tasks, as shown in the previous example. You can call forEach on your list of items to iterate through items in the list. The function you pass to forEach should take a list item as an argument, and will be executed for every item in the list.

You can process each item further by calling methods on them individually. In the previous example, we determine whether the item is a folder (StorageFolder object) or a file (StorageFile object) by comparing the result of the isOfType method, present on both files and folders , with StorageItemTypes enum value. We use this comparison to pass different information about the item to the output helper function, but you could perform a number of additional tasks as well.

For more context and to see how the outputHeader and output functions work, download the Folder enumeration sample.

When you're done, your code should look similar to this:


// Get folder
var picturesLibrary = Windows.Storage.KnownFolders.picturesLibrary;

//  Get folder contents
picturesLibrary.getItemsAsync().then(function (items) {
    // Then perform tasks with the list of files and folders that was retrieved

    // For example, display name of containing folder and count of items in folder
    outputHeader(picturesLibrary.name, items.size);

    // For example, display info for each item
    items.forEach(function (item) { 
        if (item.isOfType(Windows.Storage.StorageItemTypes.folder)) { 
            output(id(picturesLibrary.name), item.name + "\\"); 
        } 
        else { 
            output(id(picturesLibrary.name), item.fileName); 
        } 
    }); 
});

Query files in a location

Get the containing folder.

If you want to get a list of the contents of a particular folder, you must first get the folder.

The Folder enumeration sample demonstrates how to get the Pictures library:
```
var picturesLibrary = Windows.Storage.KnownFolders.picturesLibrary;
```
In the previous example, we use KnownFolders to get the Pictures library (as a StorageFolder object). You can use KnownFolders properties to get folders that represent a number of user resources such as libraries, devices, or network locations.

Important If you want to use a KnownFolders property to access a library, device, or network location your app must have the corresponding capability in its app manifest. To learn more about file access and capabilities, see File access and permissions and Access to user resources using the Windows Runtime.
Create a folder query to organize files as you specify.

When you create a folder query from a folder the files in that folder and its sub-folders are organized into groups for you, based on your criteria. The resulting groups are virtual folders that have all the functionality of a folder in file-system, allowing you to get and process the files inside them as needed.

The Folder enumeration sample demonstrates how to create a folder query that groups pictures in the Pictures library by the month they were taken or created:
```
var query = picturesLibrary.createFolderQuery(Windows.Storage.Search.CommonFolderQuery.groupByMonth);
```
As shown in the previous example, you can call createFolderQuery(query) on your folder to create a folder query (a StorageFolderQueryResult object) to organize the files in that folder and sub-folders into virtual folders based on the CommonFolderQuery value that you specify. In the example, we chose to group the picture files in the picturesLibrary folder into virtual folders based on the month (CommonFolderQuery.groupByMonth) the picture was taken or created.

You can also create folder queries by calling createFolderQuery() or createFolderQueryWithOptions.
Get the list of virtual folders from the query.

The FolderEnumeration sample on the app sample home page uses query to get the list of virtual folders:
```
query.getFoldersAsync().then(function (monthList) {
    monthList.forEach(function (month) { 
```
As shown in the previous example, you can call getFoldersAsync() on your folder query to get a list of your virtual folders. Use then to define a function that processes your list. In the example, our query returns a list of virtual folders that represent months, monthList and we process our list by calling monthList.forEach and defining a function to process each month folder.
Get the list of files in the virtual folder.

The Folder enumeration sample demonstrates how to use the month folder to get the list of pictures that were taken or created in that month:
```
        var tempMonthName = month.name; 
        month.getFilesAsync().then(function (files) {
```
Tip You may need to store information about your virtual folder (month) so that you can use it later. In the previous example, we store the name of our virtual folder (month.name) in tempMonthName so that we can use it when we process our list of pictures (files).

Use then to define a function that processes the list of files that you receive.

When you're done, your code should look similar to this:


// Get folder
var picturesLibrary = Windows.Storage.KnownFolders.picturesLibrary; 

// Create query
var query = picturesLibrary.createFolderQuery(Windows.Storage.Search.CommonFolderQuery.groupByMonth); 

// Get virtual folders from query
query.getFoldersAsync().then(function (monthList) { 
    monthList.forEach(function (month) {
 
        var tempMonthName = month.name;
        // Get files from virtual folder 
        month.getFilesAsync().then(function (files) { 
            // Then perform tasks with retrieved files
        }); 
    }); 
});