同步引擎是一种服务，它通常同步远程主机和本地客户端之间的文件。 Windows 上的同步引擎通常通过 Windows 文件系统和文件资源管理器向用户显示这些文件。 在 Windows 10 版本 1709 之前，Windows 中的同步引擎支持仅限于与方案无关的即席图面，例如文件资源管理器的导航窗格、Windows 系统托盘和（对于更多技术应用程序）文件系统筛选器驱动程序。
Windows 10 版本 1709（也称为 Fall Creators Update）引入了 云文件 API。 此 API 是正式支持同步引擎的新平台。 云文件 API 以向开发人员和最终用户提供许多新优势的方式为同步引擎提供支持。
云文件 API 包含以下本机 Win32 API 接口和 Windows 运行时 （WinRT） API 接口：
- 云筛选器 API：此原生 Win32 API 提供在用户模式和文件系统之间边界的功能。 此 API 处理占位符文件和目录的创建和管理。
- Windows.Storage.Provider 命名空间：此 WinRT API 使应用程序能够配置云存储提供程序，并将同步根注册到操作系统。
注释
云文件 API 目前不支持在 UWP 应用中实现云同步引擎。 必须在桌面应用中实现云同步引擎。
支持的功能
云文件 API 提供用于生成云同步引擎的以下功能。
占位符文件
- 同步引擎可以创建只占用 1 KB 存储空间用于文件系统标头的占位符文件，并在正常使用条件下自动转变为完整文件。 占位符文件在 Windows Shell 中以典型文件的形式呈现给应用程序和最终用户。
- 占位符文件从 Windows 内核垂直集成到 Windows Shell，并且与占位符文件的应用兼容性通常不是问题。 无论你是使用文件系统 API、命令提示符还是桌面或 UWP 应用来访问占位符文件，文件都会解除冻结，而无需进行其他代码更改，并且该应用可以正常使用该文件。
- 文件可以存在于三种状态：
- 占位符文件：文件的空表示形式，仅当同步服务可用时才可用。
- 完整文件：文件已隐式冻结，如果需要空间，系统可能会解除冻结。
- 固定的完整文件：该文件已由用户通过文件资源管理器下载，并保证可脱机使用。
下图演示了文件资源管理器中如何显示占位符、完整和固定的完整文件状态。
标准化同步根注册
注册同步根目录非常简单且标准化。 这包括在文件资源管理器导航窗格中创建品牌节点，如以下屏幕截图所示。 根可以创建为单个顶级条目，也可以创建为父级组的子级。
Shell 集成
- 状态图标：
- 云文件 API 提供文件资源管理器和 Windows 桌面中显示的标准化自动冻结状态图标。
- 除了用于冻结状态的标准 Windows 状态图标外，还可以为其他特定于服务的属性提供自定义状态图标。
- 替换旧版图标叠加层 Shell 扩展。
- 进度指示：
- 打开需要几秒钟时间进行水合的占位符文件将显示水化进度。 进度显示在几个位置，具体取决于上下文：
- 在复制引擎对话框窗口中。
- 文件资源管理器中的文件旁边会显示出来进度栏。
- 如果未在用户的特定指令中打开该文件，则会显示 Toast 通知以通知用户，并提供控制意外冻结活动的方法。
- 打开需要几秒钟时间进行水合的占位符文件将显示水化进度。 进度显示在几个位置，具体取决于上下文：
- 缩略图和元数据：
- 占位符文件可以具有丰富的服务提供的缩略图和扩展文件元数据，为用户提供无缝的文件资源管理器体验。
- 文件资源管理器导航窗格：
- 使用云文件 API 注册同步根会导致同步根（带有图标和自定义名称）显示在文件资源管理器的导航窗格中。
- 文件资源管理器上下文菜单：
- 将同步根注册到云文件 API 会自动在文件资源管理器的上下文菜单中提供多个谓词（菜单条目），让用户控制其文件的冻结状态。
- 可以使用桌面桥兼容的 API 将其他谓词添加到上下文菜单的此部分。
- 文件解除冻结的用户控制：
- 用户始终控制文件冻结，即使文件未由用户显式冻结也是如此。 将显示交互式 Toast，以便后台解除冻结，以提醒用户并提供选项。 下图演示了冻结文件的 Toast 通知。
- 如果用户通过交互式通知阻止应用程序访问文件，可以在“设置”中的“自动文件下载”页面中取消对该应用程序的阻止。
- 用户始终控制文件冻结，即使文件未由用户显式冻结也是如此。 将显示交互式 Toast，以便后台解除冻结，以提醒用户并提供选项。 下图演示了冻结文件的 Toast 通知。
- 挂钩复制引擎操作（在 Windows 10 测试版本 19624 及更高版本中受支持）：
- 云存储提供程序可以注册 shell 副本挂钩，以监视同步根中的文件作。
- 提供程序通过在其同步根注册表项下将 CopyHook 注册表值设置为其 COM 本地服务器对象的 CLSID 来注册其复制挂钩。 此本地服务器对象实现 IStorageProviderCopyHook 接口。
- 文件共享（在 Windows 11 版本 21H2 及更高版本中受支持）：
- 云存储提供程序可以注册一个共享处理程序，当用户在其同步根下的云文件上选择“共享”命令时将调用该处理程序。
- 提供程序通过将其同步根注册表项下的 ShareHandler 注册表值设置为其 COM 本地服务器对象的 CLSID 来注册其共享处理程序。 此本地服务器对象实现 IExplorerCommand 接口。
桌面桥接
- 使用云文件 API 的同步引擎旨在将 桌面桥 用作实现要求。
云镜像示例
云镜像示例演示如何生成使用云文件 API 的解决方案。 它不应用作生产代码。 它缺少可靠的错误处理，代码编写得尽量容易理解。 它称为 Cloud Mirror，因为它只是镜像本地磁盘上的本地文件夹。 指定表示云文件服务器的服务器文件夹和用于指定同步根路径的客户端文件夹。 顶级节点显示在名为 TestStorageProviderDisplayName 的文件资源管理器中的导航窗格中，此节点映射到指定的客户端文件夹。
在同步方面，以下是完全开发的云文件同步提供程序必须实现的内容：
- 当同步根文件只是占位符时，服务负责复制文件的内容以解除冻结。 在此示例中实现了该功能。
- 当同步根文件是完整文件和云服务中文件的内容发生更改时，该服务负责通知本地同步客户端更改，而本地同步客户端必须根据自己的规范处理合并。 此示例中未实现。
- 当同步根文件是完整文件和同步根路径（本地客户端）中文件的内容发生更改时，本地同步客户端必须通知云服务并根据自己的规范处理合并。 本地文件更改通知在示例中实现，但并未执行任何操作。
使用样本
- 在本地硬盘驱动器上创建两个文件夹。 其中一个将充当服务器，另一个充当客户端。
- 将某些文件添加到服务器文件夹。 确保客户端文件夹为空。
- 在 Visual Studio 中打开 Cloud Mirror 示例。 将 CloudMirrorPackage 项目设置为启动项目，然后生成并运行示例。 当示例提示时，输入服务器和客户端文件夹的两个路径。 在此之后，你将看到一个包含诊断信息的控制台窗口。
- 打开文件资源管理器并确认看到 TestStorageProviderDisplayName 节点以及复制到服务器文件夹中的所有文件的占位符。 若要模拟尝试在不使用选取器的情况下打开文件的应用程序，请将多个映像复制到服务器文件夹。 双击同步根文件夹中的其中一个，确认其冻结。 然后，打开“照片”应用。 应用将在后台预加载相邻文件，以使用户在浏览其他图片时不太可能遇到延迟。 可以通过 Toast 或在文件资源管理器中观察后台解除冻结。
- 右键单击文件资源管理器中的文件以显示上下文菜单，并确认看到 TestCommand 菜单项。 单击此菜单项将显示消息框。
- 若要停止示例，请将焦点设置为控制台输出，然后按 Ctrl-C。 这将清理同步根注册，以便卸载提供程序。 如果示例崩溃，同步根可能会保持注册状态。 这将导致每次单击任何内容时重新启动文件资源管理器，系统都会提示你输入虚假的客户端和服务器位置。 如果发生这种情况，请从计算机中卸载 CloudMirrorPackage 示例应用程序。
示例体系结构
此示例是故意简单的。 它使用静态类来避免传递实例指针。 下面是示例中的主要类：
-
FakeCloudProvider：此顶级类控制以下辅助角色类：
- CloudProviderRegistrar：向 Windows Shell 注册同步根信息。
- 占位符：在同步根路径中生成占位符文件。
- ShellServices：用于构建上下文菜单、缩略图和其他服务的 Windows Shell 提供者。
- CloudProviderSyncRootWatcher：实例化 DirectoryWatcher 以监视同步根路径的变化并响应这些变化。
- FileCopierWithProgress：将文件从服务器文件夹缓慢复制到客户端文件夹，以块形式缓慢地模拟从真正的云服务器下载这些文件。 提供进度指示，使得 Toast 和文件资源管理器界面能够显示给用户有意义的信息。
除了上述类，该示例还提供多个帮助程序类来提示用户输入文件夹和一些实用工具。 TestExplorerCommandHandler、CustomStateProvider、ThumbnailProvider 和 UriSource 都是 Shell 服务提供商的示例。
云文件 API 体系结构
云文件 API 中存储堆栈的核心是名为 cldflt.sys的文件系统微型筛选器驱动程序。 此驱动程序充当用户应用程序和同步引擎之间的代理。 同步引擎知道如何按需下载和上传数据，而 cldflt.sys 的职责是配合 Shell 来展示文件，仿佛云数据像本地数据一样可用。
Cldflt.sys 目前仅支持 NTFS 卷，因为它依赖于 NTFS 特有的某些功能。
系统中有许多文件系统微型筛选器驱动程序，它们可以同时在给定卷上处于活动状态。 对云文件 API 最感兴趣的驱动程序是防病毒文件系统筛选器。
文件系统微型筛选器驱动程序由称为筛选器管理器的特殊内核模式组件进行管理和支持。 除许多其他职责外，筛选器管理器还通过称为筛选器消息端口的构造促进筛选器和用户模式组件之间的未筛选通信。
冻结策略
Windows 支持各种 主要水化策略 和 辅助水化策略 修饰符。 主要水化策略具有以下顺序：
始终完全>>渐进>部分
应用程序和同步引擎都可以定义其首选的主要冻结策略。 如果未指定，则应用程序和同步引擎的默认冻结策略是渐进式的。
此公式在文件打开时确定云文件的冻结策略：
File hydration policy = max(app hydration policy, provider hydration policy)
例如，假设用户尝试使用 Contoso PDF 查看器打开存储在 Fabrikam Cloud Drive 上的 PDF 文件，该查看器未指定首选冻结策略。 因此，应用程序水合策略是渐进式水合，默认情况下，在本例中。 但是，由于 Fabrikam 云驱动器是一个完全冻结同步引擎，因此文件上的最终冻结策略将变为完全冻结，这将导致文件在第一次访问时完全冻结。 如果同步引擎支持渐进式冻结，但应用的首选项是完全冻结，则会出现相同的结果。
请注意，打开文件后，无法更改文件冻结策略。
与使用重新解析点的应用程序的兼容性
云文件 API 通过使用 重解析点来实现占位符系统。 对重新分析点的常见误解是它们与符号链接相同。 这种误解偶尔反映在应用程序实现中，因此，许多现有应用程序在遇到任何重新分析点时遇到错误。
为了缓解这种兼容性问题，云文件 API 始终对所有应用程序隐藏其重新解析点，只有那些主映像位于 %systemroot%下的同步引擎和进程除外。 正确理解重新分析点的应用程序可以强制平台使用 RtlSetProcessPlaceholderCompatibilityMode 或RtlSetThreadProcessPlaceholderCompatibilityMode 公开云文件 API 重新分析点。
云文件搜索
Copilot+ 电脑上支持 Windows 11 版本 24H2 及更高版本的云文件搜索。 云存储提供商可以使用以下功能来与 Windows 搜索体验集成：
- 云存储提供程序可以为其同步根目录注册文件搜索处理程序，使他们能够为文件资源管理器和 Windows 搜索贡献搜索结果。
- 云存储提供程序通过在其同步根注册表项下设置 SearchHandlerFactory 注册表值为 COM 本地服务器对象的 CLSID 来注册搜索处理程序。 此本地服务器对象实现 IStorageProviderSearchHandlerFactory 接口。
- IStorageProviderSearchHandlerFactory 创建 IStorageProviderSearchHandler 的实现。 此 IStorageProviderSearchHandler 实现调用云提供商的搜索服务，以搜索设备上可能不可用的文件。
- Windows 搜索体验在搜索期间调用 Find 方法，将其结果与本地搜索索引器的结果合并。