Создание движка облачной синхронизации с поддержкой файлов-заполнителей

Подсистема синхронизации — это служба, которая синхронизирует файлы, обычно между удаленным узлом и локальным клиентом. Подсистемы синхронизации в Windows часто представляют эти файлы пользователю через файловую систему Windows и Проводник. До Windows 10 версии 1709 поддержка подсистемы синхронизации в Windows была ограничена сценариями интерфейсов, не привязанных к конкретным задачам, таких как панель навигации Проводника, область уведомлений Windows и (для более технических приложений) драйверы фильтрации файловой системы.

Windows 10 версии 1709 (также называется Fall Creators Update) представила API облачных файлов. Этот API — это новая платформа, которая формализирует поддержку обработчиков синхронизации. API облачных файлов обеспечивает поддержку обработчиков синхронизации таким образом, что предлагает множество новых преимуществ для разработчиков и конечных пользователей.

API облачных файлов содержит следующие собственные API Win32 и API среды выполнения Windows (WinRT):

• API облачного фильтра. Этот собственный API Win32 предоставляет функциональные возможности между пользовательским режимом и файловой системой. Этот API обрабатывает создание и управление заполнителями файлов и каталогов.
• Пространство имен Windows.Storage.Provider. Этот API WinRT позволяет приложениям настроить поставщика облачного хранилища и зарегистрировать корневой каталог синхронизации в операционной системе.

Поддерживаемые функции

API облачных файлов предоставляет следующие функции для создания обработчиков облачной синхронизации.

Заполнители файлов

• Подсистемы синхронизации могут создавать файлы-заполнители, которые занимают всего 1 КБ хранилища для заголовка файловой системы, и автоматически превращаются в полные файлы при обычном использовании. Файлы заполнителей представляются как типичные файлы для приложений и конечных пользователей в оболочке Windows.
• Файлы заполнителей вертикально интегрируются из ядра Windows до оболочки Windows, а совместимость приложений с заполнителями обычно не является проблемой. Независимо от того, используете ли вы API файловой системы, командную строку или классическое приложение или приложение UWP для доступа к заполнителю, файл будет гидратироваться без дополнительных изменений кода, и это приложение может использовать файл обычно.
• Файлы могут существовать в трех состояниях:
  • Заполнитель файла: пустое представление файла и доступно только в том случае, если служба синхронизации доступна.
  • Полный файл: файл был гидратирован неявно и может быть обезвожен системой, если требуется пространство.
  • Закрепленный полный файл: файл был явно гидратирован пользователем через проводник и гарантированно доступен в автономном режиме.

На следующем изображении показано, как в Проводнике Windows отображаются состояния файла: файл-заполнитель, полный файл и закрепленный полный файл.

Стандартизованная регистрация корневой папки синхронизации

• Регистрация корня синхронизации является простой и стандартизированной. Это включает создание узла с брендом в области навигации Проводника Windows, как показано на следующем снимке экрана. Корни можно создавать как отдельные записи верхнего уровня, так и как дочерние элементы родительской группировки.

  

Интеграция оболочки

• Значки состояния:
  • API облачных файлов предоставляет стандартные, автоматические значки состояния гидратации, отображаемые в проводнике и на рабочем столе Windows.
  • Помимо стандартных значков состояния Windows, используемых для состояния гидратации, можно предоставить пользовательские значки состояния для дополнительных свойств, относящихся к службе.
  • Заменяет устаревшие расширения оболочки значка.
• Индикатор хода выполнения:
  • Открытие файла-заполнителя, гидратация которого занимает более нескольких секунд, будет отображать ход процесса. Ход выполнения отображается в нескольких расположениях в зависимости от контекста:
    • В диалоговом окне обработчика копирования.
    • Встроенный ход выполнения отображается рядом с файлом в проводнике.
    • Если файл не открыт по прямой инструкции пользователя, появляется уведомление типа toast, информирующее пользователя и предоставляющее возможность управления непреднамеренной активностью гидратации.
• Эскизы и метаданные:
  • Файлы-заполнители могут иметь богатые миниатюры, предоставляемые сервисом, и расширенные метаданные файлов, чтобы обеспечить пользователю безупречный опыт взаимодействия с Проводником файлов.
• Область навигации проводника:
  • Регистрация корневого каталога синхронизации в API облачных файлов приводит к тому, что корень синхронизации (значок и пользовательское имя) появится в области навигации проводника.
• Контекстные меню проводника:
  • Регистрация корня синхронизации в API облачных файлов автоматически предоставляет несколько команд (записей меню) в контекстном меню Файлового проводника, которые позволяют пользователю управлять состоянием синхронизации их файлов.
  • Дополнительные команды можно добавить в этот раздел контекстного меню с помощью ИНТЕРФЕЙСов API, совместимых с мостом для настольных компьютеров.
• Пользовательский контроль гидратации файлов:
  • Пользователи всегда контролируют гидратацию файлов, даже если файлы не гидратируются явным образом пользователем. Интерактивное всплывающее уведомление отображается для фоновой гидратации для оповещения пользователя и предоставления параметров. На следующем изображении показано тост-уведомление для обновляемого файла.
  • Если пользователь блокирует обновление файлов с помощью интерактивного всплывающего уведомления, он может разблокировать приложение на странице Автоматическое обновление файлов в разделе "Параметры".
• Перехват операций обработчика копирования (поддерживается в сборке предварительной версии Windows 10 Insider Preview 19624 и более поздних версиях):
  • Поставщики облачных хранилищ могут зарегистрировать перехватчик копирования оболочки для мониторинга операций с файлами в корневом каталоге синхронизации.
  • Поставщик регистрирует свой перехватчик копирования, задав значение реестра CopyHook в разделе корневого реестра синхронизации с CLSID объекта локального сервера COM. Этот локальный объект сервера реализует интерфейс IStorageProviderCopyHook .
• Общий доступ к файлам (поддерживается в Windows 11 версии 21H2 и более поздних версиях):
  • Поставщики облачных хранилищ могут зарегистрировать обработчик обмена, который будет вызываться, когда пользователь выберет команду "Поделиться" в облачном файле под их корневым каталогом синхронизации.
  • Поставщик регистрирует обработчик общих ресурсов, задав значение реестра ShareHandler под ключом корневого реестра синхронизации, соответствующим CLSID объекта локального сервера COM. Этот локальный серверный объект реализует интерфейс IExplorerCommand .

Десктоп Бридж

• Подсистемы синхронизации с помощью API облачных файлов предназначены для использования моста для настольных компьютеров в качестве требования к реализации.

Пример облачного зеркального образа

В примере Cloud Mirror показано, как создать решение, использующее API облачных файлов. Он не предназначен для использования в качестве рабочего кода. Он не имеет надежной обработки ошибок и написан так, чтобы быть максимально понятным. Она называется Cloud Mirror, так как она просто зеркально отражает локальную папку на локальном диске. Укажите папку сервера, которая предназначена для представления сервера облачных файлов и клиентской папки, предназначенной для указания корневого пути синхронизации. Узел верхнего уровня отображается в области навигации в проводнике с именем TestStorageProviderDisplayName, а этот узел сопоставляется с указанной клиентской папкой.

Когда речь идет о синхронизации, это то, что должен реализовать полностью разработанный поставщик синхронизации облачных файлов:

• Если корневой файл синхронизации является только заполнителем, служба отвечает за копирование содержимого файла для гидратации. Это реализовано в примере.
• Если корневой файл синхронизации является полным и содержимое файла в облачной службе изменяется, служба отвечает за уведомление клиента локальной синхронизации об изменении, а клиент локальной синхронизации должен обрабатывать слияния в соответствии с собственными спецификациями. Это не реализовано в примере.
• Когда файл в корне синхронизации является полным файлом и его содержимое меняется в пути синхронизации (на локальном клиенте), клиент локальной синхронизации должен уведомить облачную службу и обрабатывать слияния согласно своим спецификациям. Уведомление об изменении локального файла реализовано в примере, но это не делает ничего.

Использование примера

1. Создайте две папки на локальном жестком диске. Один из них будет выступать в качестве сервера и другого в качестве клиента.
2. Добавьте некоторые файлы в папку сервера. Убедитесь, что папка клиента пуста.
3. Откройте пример Cloud Mirror в Visual Studio. Задайте проект CloudMirrorPackage в качестве запускаемого проекта, а затем создайте и запустите пример. При появлении запроса введите два пути к папке сервера и клиентской папке. После этого появится окно консоли с диагностическими сведениями.
4. Откройте проводник и убедитесь, что вы видите узел TestStorageProviderDisplayName и заполнители для всех файлов, которые вы скопировали в папку сервера, в проводнике. Чтобы имитировать приложение, которое пытается открыть файлы без использования средства выбора, скопируйте несколько образов в папку сервера. Дважды щелкните один из них в корневой папке синхронизации и убедитесь, что она гидратирует. Затем откройте приложение "Фотографии". Приложение предварительно загружает смежные файлы в фоновом режиме, чтобы сделать его более вероятным, что пользователь не испытывает задержек при просмотре других изображений. Вы можете наблюдать за фоновым процессом дегидратации через тосты или в Проводнике.
5. Щелкните правой кнопкой мыши файл в проводнике, чтобы открыть контекстное меню, и убедитесь, что отображается пункт меню TestCommand . Если щелкнуть этот пункт меню, появится окно сообщения.
6. Чтобы остановить пример, установите фокус на выходные данные консоли и нажмите клавиши CTRL-C. Это приведет к очистке корневой регистрации синхронизации, чтобы удалить поставщика. Если образец завершится сбоем, возможно, корневой узел синхронизации останется зарегистрированным. Это приведет к тому, что Проводник будет перезапускаться каждый раз, когда вы щелкаете что-либо, и вам будет предложено указать фальшивые местоположения клиента и сервера. При этом удалите пример приложения CloudMirrorPackage с компьютера.

Пример архитектуры

Пример намеренно прост. Он использует статические классы, чтобы исключить необходимость передачи указателей экземпляра. Ниже приведены основные классы в примере:

• FakeCloudProvider: этот класс верхнего уровня управляет следующими рабочими классами:
  • CloudProviderRegistrar: регистрирует корневую информацию синхронизации в Оболочке Windows.
  • Заполнители: создает файлы заполнителей в корневом пути синхронизации.
  • ShellServices: конструирует поставщиков Windows Shell для контекстного меню, миниатюр и других служб.
  • CloudProviderSyncRootWatcher: создает экземпляр DirectoryWatcher для отслеживания изменений корневого пути синхронизации и реагирования на изменения.
  • FileCopierWithProgress: копирует файлы из папки сервера в папку клиента медленно в блоках, чтобы имитировать загрузку с реального облачного сервера. Предоставляет индикатор хода выполнения, чтобы интерфейс Проводника показывал пользователю что-то информативное.

В дополнение к приведенным выше классам, пример также предоставляет несколько вспомогательных классов, чтобы запросить у пользователя папки и некоторые утилиты. TestExplorerCommandHandler, CustomStateProvider, ThumbnailProvider и UriSource являются всеми примерами поставщиков служб Shell.

Архитектура API облачных файлов

В основе стека хранилища в API облачных файлов является драйвер мини-фильтра файловой системы с именем cldflt.sys. Этот драйвер выступает в качестве прокси-сервера между приложениями пользователя и подсистемой синхронизации. Подсистема синхронизации знает, как загружать и выгружать данные по запросу, в то время как на cldflt.sys лежит обязанность взаимодействовать с оболочкой, чтобы представлять файлы так, будто облачные данные доступны локально.

Cldflt.sys в настоящее время поддерживает только тома NTFS, так как он зависит от некоторых функций, уникальных для NTFS.

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

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

Политики гидратации

Windows поддерживает различные основные политики гидратации и вторичные модификаторы политики гидратации . Основные политики гидратации имеют следующий порядок:

Всегда полный > Полный > Прогрессивный > Частичный

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

Политика гидратации облачного файла определяется во время открытия файла с помощью этой формулы:

File hydration policy = max(app hydration policy, provider hydration policy)

Например, предположим, что пользователь пытается открыть PDF-файл, хранящийся на облачном диске Fabrikam с помощью средства просмотра PDF Contoso, который не указывает предпочтительную политику гидратации. Таким образом, политика гидратации приложений является прогрессивной гидратацией, в этом случае по умолчанию. Тем не менее, поскольку Fabrikam Cloud Drive использует механизм синхронизации с полной гидратацией, итоговая политика гидратации файла становится полной, что приведет к тому, что файл будет полностью загружен при первом доступе. Такой же результат наблюдается в случаях, когда подсистема синхронизации поддерживает постепенную загрузку, но предпочтение приложения — полная загрузка.

Обратите внимание, что политика гидратации файлов не может быть изменена после открытия файла.

Совместимость с приложениями, использующими точки повторного анализа

API облачных файлов реализует систему заполнителей с помощью репарс-точек. Распространенное неправильное представление о точках повторного сопоставления состоит в том, что они совпадают с символьными ссылками. Это неправильное представление иногда отражается в реализации приложений, и в результате многие существующие приложения сталкиваются с ошибками при обнаружении любой точки повторного анализа.

Чтобы устранить эту проблему совместимости, API облачных файлов всегда скрывает свои точки перенаправления от всех приложений, кроме синхронизационных движков и процессов, основной образ которых находится в %systemroot%. Приложения, которые правильно понимают точки повторного анализа, могут заставить платформу корректно предоставлять точки повторного анализа облачных файлов с помощью RtlSetProcessPlaceholderCompatibilityMode или RtlSetThreadProcessPlaceholderCompatibilityMode.

Поиск облачных файлов

Поиск облачных файлов поддерживается в Windows 11 версии 24H2 и более поздних версиях на компьютерах Copilot+. Следующие функции доступны для поставщиков облачных хранилищ для интеграции с интерфейсом поиска Windows:

• Поставщики облачных хранилищ могут зарегистрировать обработчик поиска файлов для корневого каталога синхронизации, что позволяет им вносить результаты поиска в проводник и поиск Windows.
• Поставщики облачных хранилищ регистрируют обработчик поиска, задав значение реестра SearchHandlerFactory в своем ключе корневого реестра синхронизации с CLSID своего объекта локального сервера COM. Этот локальный объект сервера реализует интерфейс IStorageProviderSearchHandlerFactory .
• IStorageProviderSearchHandlerFactory создает реализацию IStorageProviderSearchHandler. Эта реализация IStorageProviderSearchHandler вызывает службу поиска поставщика облачных служб для поиска файлов, которые могут быть недоступны локально на устройстве.
• Интерфейс поиска Windows вызывает метод Find во время поиска, объединяя результаты с результатами из локального индексатора поиска.

Связанный контент

Интеграция поставщика облачных файлов с Поиском Windows

IStorageProviderSearchHandlerFactory

Пространство имен Windows.Storage.Provider