Share via

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

  • Article

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.

Comments

  • Anonymous
    May 09, 2013
    Also worth noting that "Apps that apply the special use capabilities require a company account to submit them to the Windows Store." (from msdn.microsoft.com/.../hh464936.aspx). This applies to documentsLibrary, enterpriseAuthentication, and sharedUserCertificates.

  • Anonymous
    May 19, 2014
    But how can i set my FileOpenPicker.SuggestedStartLocation to that folder?

  • Anonymous
    September 10, 2014
    Ok, I am porting a corporate app we use internally that was using documentsLibrary to store a bunch of PDFs/images, then they use our app to open/view/manipulate them. I dont need to certify with the app store but it seems like it wont let me use that folder at all now, these machines are all offline, and wont be tied to one drive. The file picker doesnt work, they work by folder, not by file, and the machine could have hundreds of files on it they will work through. Any ideas? Thanks!

  • Anonymous
    December 08, 2014
    Hi Joe, Sorry for the delay. I didn't noticed your post until just now. So long as you don't need certification then the app should be able to use the documentsLibrary capability without issue. The capability was removed from the manifest designer's UI in Visual Studio 2013 so you'll need to edit it into the manifest directly. In most cases I'd still recommend using the FolderPicker (not the file picker for your scenario) to let the user choose where to place the files rather than forcing to use the documents library, but if your corporate systems are locked down sufficiently then forcing the library may be reasonable.