Accès rapide aux propriétés de fichier dans UWPFast access to file properties in UWP 

Découvrez comment récupérer rapidement une liste de fichiers et de leurs propriétés à partir d’une bibliothèque, et utiliser ces propriétés dans une application.Learn how to quickly gather a list of files and their properties from a library and use those properties in an app.  

PrérequisPrerequisites 

  • Programmation asynchrone pour applications de plateforme universelle Windows (UWP)   Vous pouvez apprendre à écrire des applications asynchrones en C# ou Visual Basic en lisant Appeler des API asynchrones en C# ou Visual Basic.Asynchronous programming for Universal Windows Platform (UWP) apps   You can learn how to write asynchronous apps in C# or Visual Basic, see Call asynchronous APIs in C# or Visual Basic. Pour apprendre à écrire des applications asynchrones en C++, voir Programmation asynchrone en C++.To learn how to write asynchronous apps in C++, see Asynchronous programming in C++. 
  • Autorisations d’accès aux bibliothèques   Le code de ces exemples nécessite la fonctionnalité picturesLibrary, mais votre emplacement de fichier peut avoir besoin d’une autre fonctionnalité, voire d’aucune.Access permissions to Libraries   The code in these examples requires the picturesLibrary capability, but your file location may require a different capability, or no capability at all. Pour en savoir plus, voir Autorisations d’accès aux fichiers.To learn more, see File access permissions. 
  • Énumération des fichiers simple    Cet exemple utilise QueryOptions pour définir quelques propriétés avancées d’énumération.Simple file enumeration    This example uses QueryOptions to set a few advanced enumeration properties. Pour en savoir plus sur l’obtention d’une simple liste de fichiers pour un petit répertoire, voir Énumérer et interroger des fichiers et dossiers.To learn more about just getting a simple list of files for a smaller directory, see Enumerate and query files and folders. 

UtilisationUsage  

De nombreuses applications doivent répertorier les propriétés d’un groupe de fichiers, mais n’ont pas toujours besoin d’interagir directement avec ceux-ci.Many apps need to list the properties of a group of files, but don't always need to interact with the files directly. Par exemple, une application de musique lit (ouvre) un fichier à la fois, mais a besoin des propriétés de tous les fichiers d’un dossier pour pouvoir afficher la file d’attente des morceaux ou pour que l’utilisateur puisse choisir un fichier valide à lire.For example, a music app plays (opens) one file at a time, but it needs the properties of all of the files in a folder so the app can show the song queue, or so the user can choose a valid file to play.

Les exemples de cette page ne doivent pas être utilisés dans des applications qui modifient les métadonnées de chaque fichier ou application interagissant avec tous les StorageFiles résultants en plus de lire leurs propriétés.The examples on this page shouldn't be used in apps that will modify the metadata of every file or apps that interact with all the resulting StorageFiles beyond reading their properties. Pour plus d’informations, voir Énumérer et interroger des fichiers et dossiers.See Enumerate and query files and folders for more information. 

Énumérer toutes les images figurant dans un emplacementEnumerate all the pictures in a location 

Dans cet exemple, nous allons :In this example, we will

  • Créer un objet QueryOptions pour spécifier que l’application souhaite énumérer les fichiers aussi rapidement que possible.Build a QueryOptions object to specify that the app wants to enumerate the files as quickly as possible.
  • Extraire les propriétés de fichier en paginant les objets StorageFile dans l’application.Fetch file properties by paging StorageFile objects into the app. La pagination des fichiers réduit la mémoire utilisée par l’application et améliore sa réactivité perçue.Paging the files in reduces the memory used by the app and improves its perceived responsiveness.

Création de la requêteCreating the query 

Pour créer la requête, nous utilisons un objet QueryOptions pour spécifier que l’application ne s’intéresse à l’énumération que de certains types de fichiers d’images et pour filtrer les fichiers protégés par la Protection des informations Windows (System.Security.EncryptionOwners).To build the query, we use a QueryOptions object to specify that the app is interested in enumerating only certain types of images files and to filter out files protected with Windows Information Protection (System.Security.EncryptionOwners). 

Il est important de définir les propriétés auxquelles l’application va accéder à l’aide de QueryOptions.SetPropertyPrefetch.It is important to set the properties the app is going to access using QueryOptions.SetPropertyPrefetch. Si l’application accède à une propriété qui n’est pas prérécupérée, cela peut entraîner une dégradation significative des performances.If the app accesses a property that isn’t prefetched, it will incur a significant performance penalty.

Le paramètre IndexerOption.OnlyUseIndexerAndOptimzeForIndexedProperties indique au système de renvoyer les résultats aussi rapidement que possible, mais d’inclure uniquement les propriétés spécifiées dans SetPropertyPrefetch.Setting IndexerOption.OnlyUseIndexerAndOptimzeForIndexedProperties tells the system to return results as quickly as possible, but to only include the properties specified in SetPropertyPrefetch.

Pagination dans les résultatsPaging in the results 

Les utilisateurs pouvant avoir des milliers ou millions de fichiers dans leur bibliothèque d’images, l’appel de GetFilesAsync surchargerait leur ordinateur, car il crée un StorageFile pour chaque image.Users may have thousands or millions of files in their pictures library, so calling GetFilesAsync would overwhelm their machine because it creates a StorageFile for each image. Cela peut être résolu en créant un nombre fixe de StorageFiles et en les traitant dans l’interface utilisateur, ce qui libère la mémoire.This can be solved by creating a fixed number of StorageFiles at one time, processing them into the UI, and then releasing the memory. 

Dans notre exemple, nous le faisons à l’aide de StorageFileQueryResult.GetFilesAsync(UInt32 StartIndex, UInt32 maxNumberOfItems) pour extraire uniquement 100 fichiers à la fois.In our example, we do this by using StorageFileQueryResult.GetFilesAsync(UInt32 StartIndex, UInt32 maxNumberOfItems) to only fetch 100 files at a time. L’application traite ensuite les fichiers et autorise le système d’exploitation à libérer cette mémoire par la suite.The app will then process the files and allow the OS to release that memory afterwards. Cette technique plafonne la mémoire maximale de l’application et garantit que le système reste réactif.This technique caps the maximum memory of the app and ensures the system stays responsive. Bien entendu, vous devez ajuster le nombre de fichiers retournés pour votre scénario mais, pour garantir une expérience réactive pour tous les utilisateurs, il est recommandé de ne pas extraire plus de 500 fichiers à la fois.Of course, you will need to adjust the number of files returned for your scenario, but to ensure a responsive experience for all users, it's recommended to not fetch more than 500 files at one time.

ExempleExample  

StorageFolder folderToEnumerate = KnownFolders.PicturesLibrary; 
// Check if the folder is indexed before doing anything. 
IndexedState folderIndexedState = await folderToEnumerate.GetIndexedStateAsync(); 
if (folderIndexedState == IndexedState.NotIndexed || folderIndexedState == IndexedState.Unknown) 
{ 
    // Only possible in indexed directories.  
    return; 
} 
 
QueryOptions picturesQuery = new QueryOptions() 
{ 
    FolderDepth = FolderDepth.Deep, 
    // Filter out all files that have WIP enabled
    ApplicationSearchFilter = "System.Security.EncryptionOwners:[]", 
    IndexerOption = IndexerOption.OnlyUseIndexerAndOptimizeForIndexedProperties 
}; 

picturesQuery.FileTypeFilter.Add(".jpg"); 
string[] otherProperties = new string[] 
{ 
    SystemProperties.GPS.LatitudeDecimal, 
    SystemProperties.GPS.LongitudeDecimal 
}; 
 
picturesQuery.SetPropertyPrefetch(PropertyPrefetchOptions.BasicProperties | PropertyPrefetchOptions.ImageProperties, 
                                    otherProperties); 
SortEntry sortOrder = new SortEntry() 
{ 
    AscendingOrder = true, 
    PropertyName = "System.FileName" // FileName property is used as an example. Any property can be used here.  
}; 
picturesQuery.SortOrder.Add(sortOrder); 
 
// Create the query and get the results 
uint index = 0; 
const uint stepSize = 100; 
if (!folderToEnumerate.AreQueryOptionsSupported(picturesQuery)) 
{ 
    log("Querying for a sort order is not supported in this location"); 
    picturesQuery.SortOrder.Clear(); 
} 
StorageFileQueryResult queryResult = folderToEnumerate.CreateFileQueryWithOptions(picturesQuery); 
IReadOnlyList<StorageFile> images = await queryResult.GetFilesAsync(index, stepSize); 
while (images.Count != 0 || index < 10000) 
{ 
    foreach (StorageFile file in images) 
    { 
        // With the OnlyUseIndexerAndOptimizeForIndexedProperties set, this won't  
        // be async. It will run synchronously. 
        var imageProps = await file.Properties.GetImagePropertiesAsync(); 
 
        // Build the UI 
        log(String.Format("{0} at {1}, {2}", 
                    file.Path, 
                    imageProps.Latitude, 
                    imageProps.Longitude)); 
    } 
    index += stepSize; 
    images = await queryResult.GetFilesAsync(index, stepSize); 
} 

RésultatsResults 

Les fichiers StorageFile obtenus contiennent uniquement les propriétés demandées, mais sont renvoyés 10 fois plus rapidement par rapport aux autres IndexerOptions.The resulting StorageFile files only contain the properties requested, but are returned 10 times faster compared to the other IndexerOptions. L’application peut toujours demander l’accès aux propriétés non incluses dans la requête, mais cela implique une baisse des performances résultant de la nécessité d’ouvrir le fichier et d’extraire ces propriétés. The app can still request access to properties not already included in the query, but there is a performance penalty to open the file and retrieve those properties.  

Ajout de dossiers à des bibliothèquesAdding folders to Libraries 

Les applications peuvent demander à l’utilisateur d’ajouter l’emplacement à l’index à l’aide de StorageLibrary.RequestAddFolderAsync.Apps can request the user to add the location to the index using StorageLibrary.RequestAddFolderAsync. Une fois l’emplacement inclus, il est automatiquement indexé et les applications peuvent utiliser cette technique pour énumérer les fichiers.Once the location is included, it will be automatically indexed and apps can use this technique to enumerate the files.  

Voir aussiSee also

Référence API QueryOptionsQueryOptions API Reference
Énumérer et interroger des fichiers et dossiersEnumerate and query files and folders
Autorisations d’accès aux fichiersFile access permissions