Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
Export (0) Print
Expand All
Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

KnownFolders.DocumentsLibrary | documentsLibrary property

Gets the Documents library. The Documents library is not intended for general use.

Syntax


var documentsLibrary = Windows.Storage.KnownFolders.documentsLibrary;

Property value

Type: StorageFolder

The Documents library.

Remarks

Note  

The Documents library is not intended for general use. For more info, see App capability declarations. Also, see the following blog post. Dealing with Documents: How (not) to use the documentsLibrary capability in Windows Store apps

If your app has to create and update files that only your app uses, consider using the app's local folder. Get the app's local folder from the Windows.Storage.ApplicationData.Current.LocalFolder property. For more info, see Quickstart: Local app data.

Or, let the user select the file location by using a file picker. For more info, see Quickstart: Accessing files with file pickers.

Prerequisites

To access the Documents library, do the following things.

  • In the app manifest, specify the Documents Library capability. This capability is not visible in Manifest Designer. To add the Documents Library capability, open the app manifest in code view and edit the XML directly. Learn more about capabilities in Access to user resources using the Windows Runtime.

  • In the app manifest, register at least one File Type Association declaration. This declaration explicitly indicates the file types (extensions) that your app wants to access in the Documents library. The app can only enumerate, create, or change files that have the file types declared in the app manifest. For more info, see How to handle file activation.

Return value

To work with the Documents library and its contents, call the methods and properties of the StorageFolder class. For general info about how to use files and folders, see Quickstart: Accessing files programmatically.

Libraries let users view related content in a single location. A library is a virtual folder. The folders in a library remain in their original locations. Learn more about libraries in Windows Libraries.

Note  

Your Windows Phone Store app can't access the Documents library in the phone's internal storage. If another app creates a Documents folder on the optional SD card, however, your app can see that folder and its contents when it enumerates folders and files.

More info

In the Documents library, the app sees only the files that correspond to the file type associations registered in the app's manifest. For example, an app that registers only the .txt file type association sees only the text files in the Documents library.

Note  

Windows Store apps only. The Documents Library typically has the following path.

%USERPROFILE%\Documents

Note  

You can't publish a Windows Phone Store app that specifies the documentsLibrary capability to the Windows Phone Store. The Store blocks the publishing of the app.

Examples

The File Access sample shows you how to use the documentsLibrary property to create a new file in the Documents library. This example assumes that the conditions described in this topic for using the Documents library in a Windows Store app have been satisfied.


Windows.Storage.KnownFolders.documentsLibrary.createFileAsync("sample.dat", Windows.Storage.CreationCollisionOption.replaceExisting).done(
   function (file) {
       // Process file
   },
   // Handle errors with an error function
   function (error) {
       // Process errors
   }
);

After the CreateFileAsync method completes, the file variable contains a StorageFile that represents the new file.

Requirements (Windows 10 device family)

Device family

Universal

API contract

Windows.Foundation.UniversalApiContract, introduced version 1.0

Namespace

Windows.Storage
Windows::Storage [C++]

Metadata

Windows.Foundation.UniversalApiContract.winmd

Capabilities

documentsLibrary

Requirements (Windows 8.x and Windows Phone 8.x)

Minimum supported client

Windows 8

Minimum supported server

Windows Server 2012

Minimum supported phone

Windows Phone 8.1 [Windows Phone Silverlight 8.1 and Windows Runtime apps]

Namespace

Windows.Storage
Windows::Storage [C++]

Metadata

Windows.winmd

Capabilities

documentsLibrary

See also

KnownFolders

 

 

Show:
© 2015 Microsoft