Быстрый доступ к свойствам файла в WinUI

Узнайте, как быстро собрать список файлов и их свойств из библиотеки и использовать эти свойства в приложении.  

Prerequisites

• Асинхронное программирование для приложений WinUI Вы можете узнать, как писать асинхронные приложения в C#, см. статью "Вызов асинхронных API" в C# или Visual Basic. Чтобы узнать, как писать асинхронные приложения в C++, см. раздел Асинхронное программирование в C++. 
• Доступ к библиотекам Для кода в этих примерах требуется возможность доступа к библиотеке изображений, но расположение файла может требовать другой возможности доступа или вообще может не требовать её. Дополнительные сведения см. в разделе "Разрешения на доступ к файлам". 
• Простое перечисление файлов В этом примере для задания нескольких расширенных свойств перечисления используется QueryOptions . Дополнительные сведения о простом получении простого списка файлов для меньшего каталога см. в разделе "Перечисление" и "Запрос файлов и папок". 

Употребление

Многие приложения должны перечислять свойства группы файлов, но не всегда нужно взаимодействовать с файлами напрямую. Например, музыкальное приложение воспроизводит (открывает) один файл за раз, но он нуждается в свойствах всех файлов в папке, чтобы приложение может отображать очередь песни или таким образом, чтобы пользователь мог выбрать допустимый файл для воспроизведения.

Примеры на этой странице не должны использоваться в приложениях, которые изменят метаданные каждого файла или приложений, взаимодействующих со всеми результированными файлами StorageFiles за пределами чтения их свойств. Дополнительные сведения см. в разделе "Перечисление и запрос файлов и папок ". 

Перечислить все изображения в месте

В этом примере мы будем

• Создайте объект QueryOptions , чтобы указать, что приложение хочет перечислить файлы как можно быстрее.
• Получение свойств файла путем разбиения объектов StorageFile в приложение. Загрузка страниц файлов в память уменьшает использование памяти приложением и улучшает воспринимаемую отзывчивость приложения.

Создание запроса

Чтобы создать запрос, мы используем объект QueryOptions, чтобы указать, что приложение заинтересовано в перечислении только определенных типов файлов изображений и фильтрации файлов, защищенных с помощью Windows Information Protection (System.Security.EncryptionOwners). 

Важно задать свойства, к которые приложение будет получать доступ с помощью QueryOptions.SetPropertyPrefetch. Если приложение обращается к свойству, которое не было предварительно загружено, это приведет к значительному снижению производительности.

Параметр IndexerOption.OnlyUseIndexerAndOptimzeForIndexedProperties сообщает системе как можно быстрее возвращать результаты, но включать только свойства, указанные в SetPropertyPrefetch.

Разбиение по страницам в результатах

Пользователи могут иметь тысячи или миллионы файлов в библиотеке изображений, поэтому вызов GetFilesAsync будет перегружен их компьютером, так как он создает StorageFile для каждого образа. Это можно решить, создав фиксированное количество файлов StorageFile в один раз, обработать их в пользовательском интерфейсе, а затем освободить память. 

В нашем примере мы делаем это с помощью StorageFileQueryResult.GetFilesAsync(UInt32 StartIndex, UInt32 maxNumberOfItems) для получения только 100 файлов за раз. Затем приложение обработает файлы и позволит ОС освободить ее после этого. Этот метод задерживает максимальную память приложения и гарантирует, что система будет реагировать. Конечно, вам потребуется настроить количество файлов, возвращенных для вашего сценария, но чтобы обеспечить адаптивный интерфейс для всех пользователей, рекомендуется не получить более 500 файлов одновременно.

Пример

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); 
} 

Результаты

Полученные файлы StorageFile содержат только запрошенные свойства, но возвращаются 10 раз быстрее по сравнению с другими IndexerOptions. Приложение по-прежнему может запрашивать доступ к свойствам, которые еще не включены в запрос, но за это приходится платить снижением производительности при открытии файла и извлечении этих свойств.  

Добавление папок в библиотеки

Приложения могут запросить у пользователя добавление расположения в индекс с помощью StorageLibrary.RequestAddFolderAsync. Как только расположение будет добавлено, оно будет автоматически индексировано, и приложения могут использовать этот метод для обработки файлов.  

См. также

Справочник по API QueryOptions
Перечисление и запрос файлов и папок
Разрешения доступа к файлам