Using Neighbouring File Queries to Power your App

  • Article

Neighbouring files queries (NFQ) were originally introduced in Windows 8 and we have extended them for the Universal Windows Platform. NFQs allow for users to maintain context on their files as they move between apps by allow apps to pass a list of related files along with a normal file activation.

 

What is an Neighbouring file query?

It is a group of files that are included with a file activation to allow the target app to keep the user's context. The most common example of this in Windows is when you open a picture from a folder in file explorer. File explorer creates an NFQ which it includes with the file activation. The photos app is then able to provide an experience for users to move through the rest of the files in the same folder, without being explicitly activated for those files.

Who is expected to set NFQs?

Any apps using a file activation in their experiences and wish to allow their users to potentially see other, related files in the target app as well. For example if the user has received a number of images as a message attachment, they expect to be able to scroll through their images in a photo viewer without having to go back to the messaging app each time.

An NFQ should not be used for activating apps when the user is expecting the target app to use all the files in the query immediately, such as a multi-select scenario in files explorer. It should only be used as an optional hint to the target app.

Who should respond to NFQs?

Any app that registers for file activations and can do something interesting if there are files related to the one they are opening. Video and picture viewing apps are a good example of an app that can do something interesting with a series of files. A document editing app might not respond to an NFQ, as they don't have a scenario where a user is scrolling through multiple documents.

 

Example: Setting an NFQ in a Source Apps

We are going to walk through a quick example of how to create an NFQ for a source app that has a picture album stored in its local folder. In this case the source app wants to launch the photo viewer to view a single image, but enable the user to be able to scroll through all the images in the same folder.

Creating an NFQ starts with first finding the file that you are going to launch. In this case we are going to use a file that is stored in our app's local folder, but it is possible to do this with any file your app has access to.

 
StorageFolder sourceFolder = ApplicationData.Current.LocalFolder;
StorageFile fileToLaunch = await sourceFolder.GetFileAsync("launchingFile.jpg");

Next we need to find any files that are related to the file we are launching. To do this we build up a query that includes all the pictures in the same folder.

 
QueryOptions queryOptions = newQueryOptions();
//Note that you can have a more restrictive condition here (ext:.jpg OR ext:.jpeg) 
//but I've chosen to error on the side of giving the target app more files to work 
//with and if it can only handle jpegs, it needs to do its own filtering
queryOptions.ApplicationSearchFilter = "kind:picture";  queryOptions.FolderDepth = FolderDepth.Shallow;
//Important since we are in the app data container where there is no indexing
IndexerOption.DoNotUseIndexer;
StorageFileQueryResult nfq = SourceFolder.CreateFileQueryWithOptions(queryOptions);

You can get as creative here as you'd like with the ApplicationSearchFilter and other options, but I'm keeping the result set very broad. This will enable the target app to provide a richer experience or do further filtering themselves.

The final step is to attach the NFQ to the launcher options and launch the target app.

 LauncherOptions launcherOptions = new LauncherOptions();
launcherOptions.NeighboringFilesQuery = nfq;
Launcher.LaunchFileAsync(fileToLaunch, launcherOptions);

And that is it. The default handler will be launched along to handle the file you've chosen along with another other files in the NFQ. For example you can see in the following image how I've been able to launch the photos app and have it displaying the arrow hints on the side which indicate the user can scroll to view more images in the collection

Example: Consuming an NFQ in a Target App

Consuming an NFQ is a very simple process, and can allow you to build more useful experiences for your users. There are two parts to consuming an NFQ, first the manifest must include the correct registration information and then a bit of code in the target app the handle the activation.

We will briefly touch on file activations, but for more detail see the article How to handle file activation.

Manifest Registration

Your app is going to have to register for the file types that it can be activated for and the more general kind of files it would be able to handle in an NFQ.

Files Type Registration

This is where your app can register for the types that is going to be activated to handle. There is an edit experience in Visual Studio and more details available but for now we are going to manually edit the package.appxmanifest to add a registration for .jpeg and .jpg.

         <uap:ExtensionCategory="windows.fileTypeAssociation">  
          <uap:FileTypeAssociationName="image"DesiredView="useMore">  
            <uap:EditFlagsOpenIsSafe="true"AlwaysUnsafe="false"/>  
            <uap:SupportedFileTypes>  
              <uap:FileTypeContentType="image/jpeg">.jpeg</uap:FileType>  
              <uap:FileTypeContentType="image/jpeg">.jpg</uap:FileType>  
            </uap:SupportedFileTypes>  
          </uap:FileTypeAssociation>  
        </uap:Extension>

Note that the uap namespace is going to be new for Windows 10, but otherwise the registration is unchanged from Windows and Windows Phone 8.1 universal apps.

File Kind Registration

Your app also has to register for the kind of files that it is interested in being able to view in an NFQ. It does this by registering for access to the library of the kind of files it would like to see.

For example, my app is going to be able to view picture files, so it will register for the pictures library capability.

     <uap:CapabilityName="picturesLibrary"/>

 

Apps that can handle video or music types would register for the appropriate libraries. The mapping between capabilities and files extensions is outlined in more detail here.

The NFQ that is received by your app will be filtered down to only the kind of files it is registered for. This it to make sure that apps are not going to be stuck dealing with massive queries filled with files they can't use.

Note that if you don't have any library capabilities and try to access a NFQ you will get an AccessDenied exception.

Opening the NFQ in Code

To get access to the NFQ in your app you are first going to have to implement the OnFileActivated method in your App class.

   protectedoverridevoid OnFileActivated(FileActivatedEventArgs e)

 

Then to get the NFQ you simply have to read the NeighboringFilesQuery from the FileActivatedEventArgs as shown below.

   StorageFileQueryResult query = e.NeighboringFilesQuery;

 

And that is it. Your app now has access to all the files in the query and can use them in the experience to help your customers complete whatever action they are doing easily.