建置支援佔位符檔案的雲端同步引擎

  • 發行項

同步處理引擎是同步處理檔案的服務，通常是在遠端主機與本機客戶端之間。 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 會處理佔位元檔案和目錄的建立和管理。
  • 窗戶。儲存體。提供者命名空間：此 WinRT API 可讓應用程式設定雲端記憶體提供者，並與作業系統註冊同步根目錄。

注意

雲端檔案 API 目前不支援在 UWP 應用程式中實作雲端同步引擎。 雲端同步引擎必須在傳統型應用程式中實作。

支援的功能

雲端檔案 API 提供下列功能來建置雲端同步引擎。

佔位符檔案

  • 同步處理引擎可以建立佔位元檔案，只針對文件系統標頭取用 1 KB 的記憶體，並在正常使用條件下自動凍結到完整檔案。 佔位符檔案會以一般檔案的形式呈現給 App 和 Windows Shell 中的使用者。
  • 占位符檔案會從 Windows 核心垂直整合至 Windows Shell，而與佔位符檔案的應用程式相容性通常是非問題。 無論您使用檔案系統 API、命令提示字元或桌面或 UWP 應用程式來存取佔位元檔案，檔案都會解除凍結，而不需要進行額外的程式碼變更，而且該應用程式可以正常使用檔案。
  • 檔案可以存在於三種狀態：
    • 占位符檔案：檔案的空白表示法，只有在同步處理服務可供使用時才可使用。
    • 完整檔案：檔案已隱含凍結，如果需要空間，系統可能會脫水。
    • 已釘選的完整檔案：使用者已透過 檔案總管 明確凍結檔案，並保證可供脫機使用。

下圖示範如何在 檔案總管 中顯示佔位元、完整和釘選的完整檔案狀態。

Example of three file states in File Explorer

標準化同步根註冊

  • 註冊同步根目錄很簡單且標準化。 這包括在 檔案總管 瀏覽窗格中建立品牌節點，如下列螢幕快照所示。 根可以建立為個別的最上層專案，或做為父群組的子系。

    Example of a sync root entry in File Explorer

殼層整合

  • 狀態圖示：
    • 雲端檔案 API 提供 檔案總管 和 Windows 桌面上顯示的標準化、自動凍結狀態圖示。
    • 除了用於凍結狀態的標準 Windows 狀態圖示之外，您還可以提供其他服務特定屬性的自定義狀態圖示。
    • 取代舊版圖示重疊殼層延伸模組。
  • 進度指示：
    • 開啟需要幾秒鐘才能凍結的佔位符檔案會顯示凍結進度。 進度會顯示在幾個位置，視內容而定：
      • 在複製引擎對話框視窗中。
      • 內嵌進度會顯示在 檔案總管 檔案旁邊。
      • 如果未在使用者的特定指示開啟檔案，則會顯示快顯通知來通知使用者，並提供控制非預期凍結活動的方法。
  • 縮圖和元資料：
    • 占位元檔案可以有豐富的服務提供的縮圖和延伸的檔案元數據，為使用者提供順暢的 檔案總管 體驗。
  • 檔案總管 瀏覽窗格：
    • 向雲端檔案 API 註冊同步根目錄會導致同步根目錄（具有圖示和自定義名稱）出現在 檔案總管 的瀏覽窗格中。
  • 檔案總管 操作功能表：
    • 向雲端檔案 API 註冊同步根目錄時，會自動在 檔案總管 的操作功能表中提供數個動詞（功能表項），讓使用者控制其檔案的凍結狀態。
    • 您可以使用 傳統型橋接器 相容 API，將其他動詞新增至操作功能表的這個區段。
  • 檔案凍結的使用者控制：
    • 使用者一律會控制檔案凍結，即使使用者未明確凍結檔案也一樣。 背景凍結會顯示互動式快顯通知，以警示使用者並提供選項。 下圖示範水化檔案的快顯通知。 Example of an interactive toast shown for background file hydration
    • 如果使用者封鎖應用程式透過互動式快顯通知將檔案凍結，他們可以在 [自動下載檔案] 頁面中解除封鎖應用程式，設定。 Screenshot of the automatic file downloads setting
  • 鏈接複製引擎作業（Windows 10 Insider Preview 組建 19624 和更新版本支援）：
    • 雲端記憶體提供者可以註冊殼層複製勾點，以監視其同步根目錄內的檔案作業。
    • 提供者藉由將 CopyHook 登錄機碼下的 CopyHook 登錄值設定為其 COM 本地伺服器物件的 CLSID 來註冊其複製勾點。 這個本地伺服器物件會實作 I 儲存體 ProviderCopyHook 介面。
  • 檔案共享 （Windows 11 版本 21H2 和更新版本支援）：
    • 雲端記憶體提供者可以註冊共用處理程式，當使用者在其同步根目錄下選取雲端檔案上的 「共用」命令時，就會叫用該處理程式。
    • 提供者藉由將 ShareHandler 登錄機碼下的 ShareHandler 登錄值設定為 COM 本機伺服器物件的 CLSID，以註冊其共用處理程式。 這個本地伺服器物件會實作 IExplorerCommand 介面。

傳統型橋接器

  • 使用雲端檔案 API 的同步處理引擎是設計來使用 傳統型橋接器 作為實作需求。

雲端鏡像範例

雲端 鏡像範例 說明如何建置使用雲端檔案 API 的解決方案。 它不打算當做生產程序代碼使用。 它缺少強固的錯誤處理，而且會撰寫成盡可能容易理解。 它稱為 Cloud Mirror，因為它只會鏡像本機磁碟上的本機資料夾。 您可以指定代表雲端檔案伺服器的伺服器資料夾，以及用來指定同步根路徑的客戶端資料夾。 最上層節點會出現在名為 Test 儲存體 ProviderDisplayName 的瀏覽 檔案總管 窗格中，且此節點會對應至指定的客戶端資料夾。

在同步處理方面，以下是完全開發雲端檔案同步提供者必須實作的專案：

  • 當同步根檔案只是佔位元元時，服務會負責複製檔案的內容以進行凍結。 這會在範例中實作。
  • 當同步根檔案是完整檔案，且雲端服務中的檔案內容變更時，服務會負責通知本機同步客戶端變更，而本機同步客戶端必須根據自己的規格處理合併。 這不會在範例中實作。
  • 當同步根檔案是完整檔案，且同步根路徑中的檔案內容變更時，本機同步客戶端必須通知雲端服務，並根據自己的規格處理合併。 本機檔案變更通知會在範例中實作，但不會執行任何動作。

使用範例

  1. 在您的本機硬碟上建立兩個資料夾。 其中一個將作為伺服器，另一個做為用戶端。
  2. 將一些檔案新增至伺服器資料夾。 請確定客戶端資料夾是空的。
  3. 在 Visual Studio 中開啟 Cloud Mirror 範例。 將 CloudMirrorPackage 專案設定為啟始專案，然後建置 並執行範例。 當範例提示時，請輸入伺服器和用戶端資料夾的兩個路徑。 在此之後，您會看到具有診斷資訊的控制台視窗。
  4. 開啟 檔案總管，並確認您看到 Test 儲存體 ProviderDisplayName 節點，以及您複製到伺服器資料夾之所有檔案的佔位符。 若要模擬嘗試在不使用選擇器的情況下開啟檔案的應用程式，請將數個映像複製到伺服器資料夾。 按兩下同步根資料夾中的其中一個，並確認凍結。 然後，開啟 [相片] 應用程式。 應用程式會在背景預先載入相鄰的檔案，讓使用者在查看其他圖片時不會遇到延遲。 您可以透過快顯通知或 檔案總管 來觀察背景凍結。
  5. 以滑鼠右鍵按下 檔案總管 中的檔案以顯示操作功能表，並確認您看到 TestCommand 選單項。 按下此功能表項會顯示消息框。
  6. 若要停止範例，請將焦點設定為控制台輸出，然後按 Ctrl-C。 這會清除同步根登錄，讓提供者卸載。 如果範例當機，同步根目錄可能會保持註冊。 這會導致每次按下任何專案時重新啟動 檔案總管，而且系統會提示您輸入假用戶端和伺服器位置。 如果發生這種情況，請 從您的電腦卸載 CloudMirrorPackage 範例應用程式。

範例架構

此範例是刻意簡單的。 它會使用靜態類別，使其不需要傳遞實例指標。 以下是範例中的主要類別：

  • FakeCloudProvider：此最上層類別可控制下列背景工作類別：
    • CloudProviderRegistrar：向 Windows Shell 註冊同步根資訊。
    • 佔位元：在同步根路徑中產生佔位元檔案。
    • ShellServices：建構操作功能表、縮圖和其他服務的 Windows Shell 提供者。
    • CloudProviderSyncRootWatcher：具現化 DirectoryWatcher 來監視同步根路徑的變更，並處理變更。
    • FileCopierWithProgress：將檔案從伺服器資料夾複製到客戶端資料夾，以緩慢的區塊執行，以模擬從實際雲端伺服器下載它們。 提供進度指示，讓快顯通知和 檔案總管 UI 向使用者顯示資訊。

除了上述類別之外，此範例也會提供數個協助程序類別來提示使用者輸入資料夾和某些公用程式。 TestExplorerCommandHandler、CustomStateProvider、ThumbnailProvider 和 UriSource 都是 Shell 服務提供者的範例。

雲端檔案 API 架構

雲端檔案 API 中記憶體堆疊的核心是稱為 cldflt.sys 的文件系統迷你篩選驅動程式。 此驅動程式可作為使用者應用程式與同步處理引擎之間的 Proxy。 同步處理引擎知道如何視需要下載和上傳數據，同時負責cldflt.sys使用 Shell 來呈現檔案，就像雲端數據在本機可用一樣。

Cldflt.sys目前僅支援NTFS磁碟區，因為它取決於NTFS特有的某些功能。

系統中有許多檔系統小型篩選驅動程式，而且可以在指定的磁碟區上同時作用中。 雲端檔案 API 最感興趣的驅動程式是防病毒軟體檔系統篩選器。

檔系統迷你篩選驅動程式是由稱為篩選管理員的特殊內核模式元件所管理及支援。 除了許多其他職責之外，篩選管理員可透過稱為篩選消息埠的建構，促進篩選和使用者模式元件之間的未篩選通訊。

凍結原則

Windows 支持各種 主要水化原則 和 次要水化原則 修飾詞。 主要水化原則有下列順序：

一律完整漸進 >>> 部分

應用程式和同步處理引擎都可以定義其慣用的主要凍結原則。 如果未指定，則應用程式與同步處理引擎的預設凍結原則為漸進式。

雲端檔案的凍結原則是由此公式在檔案開啟時間決定：

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

例如，假設用戶嘗試使用 Contoso PDF Viewer 開啟儲存在 Fabrikam Cloud Drive 上的 PDF 檔案，但未指定慣用的凍結原則。 因此，應用程式解除凍結原則是漸進式凍結，在此案例中預設為 。 不過，因為 Fabrikam 雲端磁碟驅動器是完整的凍結同步處理引擎，所以檔案上的最終凍結原則會變成完整凍結，這會導致檔案在第一次存取時完全凍結。 在同步處理引擎支援漸進式凍結的情況下，會發生相同的結果，但應用程式的喜好設定是完全凍結。

請注意，開啟檔案之後，就無法變更檔案凍結原則。

與使用重新分析點的應用程式相容

雲端檔案 API 會使用 重新分析點來實作佔位元元系統。 重新分析點的常見誤解是，它們與符號連結相同。 這種誤解偶爾會反映在應用程式實作中，因此，許多現有的應用程式在遇到任何重新分析點時遇到錯誤。

為了減輕此相容性問題，雲端檔案 API 一律會隱藏所有應用程式的重新分析點，但主要映像位於 %systemroot% 之下的同步處理引擎和進程除外。 瞭解重新剖析點的應用程式可以強制平臺使用 RtlSetProcessPlaceholderCompatibilityMode 或 RtlSetThreadProcessPlaceholderCompatibilityMode 公開雲端檔案 API 重新分析點。