Dealing with Documents: How (not) to use the documentsLibrary capability in Windows Store apps

Many people posting in the forums express confusion over the documentsLibrary capability's "Special Use" categorization.

This capability is highly restricted and not intended for general use, and apps which try to use it generally will fail certification.

While the requirements that business accounts are required to declare the Special Use capabilities and that only specifically declared file types can be used are what usually catch the eye, the limitation most apps run into is that "the only acceptable use for the documentsLibrary capability is to support the opening of embedded content within another document". This capability is not intended to allow apps to use the documents library as general storage or to allow programmatic browsing of the library. We strongly recommend you avoid using this capability.

What does an app do if it needs to store user-facing documents?

The good news is that most apps will be better off without the documentsLibrary. Instead, allow the user the flexibility to choose which folder to use. The first time a document needs to be saved pop up a FolderPicker to let the user choose where to place it. Remember the location in the FutureAccessList so the user only has to choose the first time.

Users can choose the Documents folder if they want. Users who prefer other locations can choose them. For example: I keep most of my documents in my SkyDrive folders! 

For more information on the FolderPicker see Quickstart: Accessing files with file pickers and the File picker sample. For more information about caching the file access see  How to track recently used files and folders and the File access sample.

--Rob

Follow the Windows Store Developer Solutions team on Twitter @wsdevsol.