次の方法で共有

プレースホルダー ファイルをサポートするクラウド同期エンジンを構築する

同期エンジンは、通常、リモート ホストとローカル クライアントの間でファイルを同期するサービスです。 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 シェルのアプリおよびエンド ユーザーに対して、一般的なファイルとして存在するプレースホルダー ファイル。
  • プレースホルダー ファイルは Windows カーネルから Windows シェルまで垂直方向に統合されており、プレースホルダー ファイルとのアプリの互換性は一般に問題ではありません。 ファイル システム API、コマンド プロンプト、デスクトップ、または UWP アプリを使用してプレースホルダー ファイルにアクセスする場合でも、ファイルは追加のコード変更なしでハイドレートされ、そのアプリは通常どおりファイルを使用できます。
  • ファイルは、次の 3 つの状態で存在できます。
    • プレースホルダー ファイル: ファイルの空の表現であり、同期サービスが使用可能な場合にのみ使用できます。
    • ファイル全体: ファイルは暗黙的にハイドレートされ、領域が必要な場合はシステムによって脱水される可能性があります。
    • 固定された完全なファイル: ファイルはエクスプローラーを介してユーザーによって明示的にハイドレートされており、オフラインで使用できる状態であることが保証されています。

次の図は、エクスプローラーでプレースホルダー、完全、固定された完全なファイルの状態がどのように表示されるかを示しています。

エクスプローラーでの 3 つのファイル状態の例

標準化された同期ルート登録

  • 同期ルートの登録は簡単で標準化されています。 これには、次のスクリーンショットに示すように、エクスプローラーのナビゲーション ウィンドウでのブランド化されたノードの作成が含まれます。 ルートは、最上位レベルのエントリとして個別に作成することも、親のグループの子要素として作成することもできます。

    エクスプローラーでの同期ルート エントリの例

シェル統合

  • 状態アイコン:
    • クラウド ファイル API には、エクスプローラーと Windows デスクトップに表示される標準化された自動ハイドレーション状態アイコンが用意されています。
    • ハイドレーション状態に使用される標準の Windows 状態アイコンに加えて、サービス固有の追加プロパティ用のカスタム状態アイコンを指定できます。
    • 従来のアイコン オーバーレイ シェル拡張機能を置き換えます。
  • 進行状況の表示:
    • ハイドレートに数秒以上かかるプレースホルダー ファイルを開くと、ハイドレーションの進行状況が表示されます。 進行状況は、コンテキストに応じていくつかの場所に表示されます。
      • [コピー エンジン] ダイアログ ウィンドウで。
      • エクスプローラーでファイルの横にインラインの進行状況が表示されます。
      • ユーザーが特定の指示でファイルを開いていない場合は、トースト通知が表示され、ユーザーにそのことを知らせるとともに、意図しないハイドレーションアクティビティを管理する方法が提示されます。
  • サムネイルとメタデータ:
    • プレースホルダー ファイルには、サービスで提供される豊富なサムネイルと拡張ファイル メタデータを使用して、シームレスなエクスプローラー エクスペリエンスをユーザーに提供できます。
  • エクスプローラーのナビゲーション ウィンドウ:
    • クラウド ファイル API に同期ルートを登録すると、その同期ルート (アイコンとカスタム名) がエクスプローラーのナビゲーション ウィンドウに表示されます。
  • ファイル エクスプローラーのコンテキスト メニュー
    • クラウド ファイル API に同期ルートを登録すると、エクスプローラーのコンテキスト メニューに複数の動詞 (メニュー エントリ) が自動的に提供され、ユーザーはファイルのハイドレーション状態を制御できます。
    • デスクトップ ブリッジ互換 API を使用して、コンテキスト メニューのこのセクションに追加の動詞を追加できます。
  • ファイルハイドレーションのユーザー制御:
    • ファイルがユーザーによって明示的にハイドレートされていない場合でも、ユーザーは常にファイルハイドレートを制御します。 ユーザーに警告し、オプションを提供するために、バックグラウンドハイドレーション用の対話型トーストが表示されます。 次の図は、ハイドレート ファイルのトースト通知を示しています。 バックグラウンド ファイルハイドレーション用に表示される対話型トーストの例
    • ユーザーが対話型トーストを介してアプリがファイルのハイドレートをブロックしている場合は、[設定] の [自動ファイルダウンロード] ページでアプリのブロックを解除できます。 ファイルの自動ダウンロード設定のスクリーンショット
  • コピーエンジンの操作をフックする (Windows 10 Insider Preview ビルド 19624 以降のバージョンでサポート):
    • クラウド ストレージ プロバイダーは、同期ルート内のファイル操作を監視するためのシェル コピー フックを登録できます。
    • プロバイダーは、同期ルート レジストリ キーの CopyHook レジストリ値を COM ローカル サーバー オブジェクトの CLSID に設定することで、コピー フックを登録します。 このローカル サーバー オブジェクトは、 IStorageProviderCopyHook インターフェイスを 実装します。
  • ファイル共有 (Windows 11 バージョン 21H2 以降のバージョンでサポート):
    • クラウド ストレージ プロバイダーは、ユーザーが同期ルートの下にあるクラウド ファイルで [共有] コマンドを選択したときに呼び出される共有ハンドラーを登録できます。
    • プロバイダーは、同期ルート レジストリ キーの ShareHandler レジストリ値を COM ローカル サーバー オブジェクトの CLSID に設定することで、共有ハンドラーを登録します。 このローカル サーバー オブジェクトは 、IExplorerCommand インターフェイスを 実装します。

デスクトップ ブリッジ

  • クラウド ファイル API を使用する同期エンジンは、実装要件として デスクトップ ブリッジ を使用するように設計されています。

クラウド ミラーのサンプル

クラウド ミラーサンプルは、クラウド ファイル API を使用するソリューションを構築する方法を示しています。 運用コードとして使用するためのものではありません。 それは堅牢なエラー処理を欠いており、可能な限り簡単に理解できるように書かれています。 クラウド ミラーと呼ばれるのは、ローカル ディスク上のローカル フォルダーを単にミラー化するためです。 クラウド ファイル サーバーを表すサーバー フォルダーと、同期ルート パスを指定するためのクライアント フォルダーを指定します。 エクスプローラーのナビゲーション ウィンドウに TestStorageProviderDisplayName という最上位ノードが表示され、このノードは指定されたクライアント フォルダーにマップされます。

同期に関しては、完全に開発されたクラウド ファイル同期プロバイダーが実装する必要がある要素を次に示します。

  • 同期ルート ファイルが単なるプレースホルダーである場合、サービスはハイドレーションのためにファイルの内容をコピーします。 これはサンプルで実装されています。
  • 同期ルート ファイルが完全なファイルであり、クラウド サービス内のファイルの内容が変更された場合、サービスはローカル同期クライアントに変更を通知し、ローカル同期クライアントは独自の仕様に従ってマージを処理する必要があります。 これはサンプルでは実装されていません。
  • 同期ルート ファイルが完全なファイルであり、同期ルート パス (ローカル クライアント) 内のファイルの内容が変更された場合、ローカル同期クライアントはクラウド サービスに通知し、独自の仕様に従ってマージを処理する必要があります。 ローカル ファイル変更通知はサンプルに実装されていますが、何も行いません。

サンプルを使用する

  1. ローカル ハード ドライブに 2 つのフォルダーを作成します。 そのうちの 1 つはサーバーとして機能し、もう 1 つはクライアントとして機能します。
  2. サーバー フォルダーにいくつかのファイルを追加します。 クライアント フォルダーが空であることを確認します。
  3. Visual Studio でクラウド ミラー サンプルを開きます。 CloudMirrorPackage プロジェクトをスタートアップ プロジェクトとして設定し、サンプルをビルドして実行します。 サンプルのプロンプトが表示されたら、サーバー フォルダーとクライアント フォルダーへの 2 つのパスを入力します。 その後、診断情報を含むコンソール ウィンドウが表示されます。
  4. エクスプローラーを開き、 TestStorageProviderDisplayName ノードと、サーバー フォルダーにコピーしたすべてのファイルのプレースホルダーが表示されることを確認します。 ピッカーを使用せずにファイルを開こうとするアプリケーションをシミュレートするには、複数のイメージをサーバー フォルダーにコピーします。 同期ルート フォルダー内のそのうちの 1 つをダブルクリックし、ハイドレートされることを確認します。 次に、フォト アプリを開きます。 アプリはバックグラウンドで隣接するファイルを事前に読み込み、ユーザーが他の画像を見ているときに遅延が発生しない可能性が高くなります。 トーストまたはエクスプローラーで、バックグラウンドの脱水が発生しているのを確認できます。
  5. エクスプローラーでファイルを右クリックしてコンテキスト メニューを表示し、 TestCommand メニュー項目が表示されることを確認します。 このメニュー項目をクリックすると、メッセージ ボックスが表示されます。
  6. サンプルを停止するには、コンソール出力にフォーカスを設定し、 Ctrl キーを押しながら C キーを押します。 これにより、同期ルート登録がクリーンアップされ、プロバイダーがアンインストールされます。 サンプルがクラッシュした場合、同期ルートが登録されたままになる可能性があります。 これにより、何かをクリックするたびにエクスプローラーが再起動され、偽のクライアントとサーバーの場所を確認するメッセージが表示されます。 この場合は、コンピューターから CloudMirrorPackage サンプル アプリケーションをアンインストールします。

サンプル アーキテクチャ

サンプルは意図的に単純です。 静的クラスを使用して、インスタンス ポインターを渡す必要が無いようにします。 サンプルの主なクラスを次に示します。

  • FakeCloudProvider: この最上位クラスは、次のワーカー クラスを制御します。
    • CloudProviderRegistrar: 同期ルート情報を Windows シェルに登録します。
    • プレースホルダー: 同期ルート パスにプレースホルダー ファイルを生成します。
    • ShellServices: コンテキスト メニュー、サムネイル、およびその他のサービス用の Windows シェル プロバイダーを構築します。
    • CloudProviderSyncRootWatcher: DirectoryWatcher をインスタンス化して同期ルート パスへの変更を監視し、変更に対処します。
    • FileCopierWithProgress: サーバー フォルダーからクライアント フォルダーにファイルをチャンク単位でゆっくりとコピーし、実際のクラウド サーバーからのダウンロードをシミュレートします。 進捗状況を示すことで、トーストやファイルエクスプローラーのUIにユーザーに役立つ情報が表示されます。

上記のクラスに加えて、サンプルには、ユーザーにフォルダーといくつかのユーティリティの入力を求めるヘルパー クラスがいくつか用意されています。 TestExplorerCommandHandler、CustomStateProvider、ThumbnailProvider、UriSource はすべてシェル サービス プロバイダーの例です。

クラウド ファイル API のアーキテクチャ

クラウド ファイル API のストレージ スタックの中核となるのは、cldflt.sysと呼ばれるファイル システム ミニフィルター ドライバーです。 このドライバーは、ユーザーのアプリケーションと同期エンジンの間のプロキシとして機能します。 同期エンジンは、必要に応じてデータをダウンロードしてアップロードする方法を認識しますが、クラウド データがローカルで使用可能であるかのようにファイルを表示するには、シェルと連携する cldflt.sys が必要です。

現在、Cldflt.sys は NTFS ボリュームのみをサポートしています。NTFS に固有の一部の機能に依存するためです。

システムには多くのファイル システム ミニフィルター ドライバーがあり、特定のボリュームで同時にアクティブにすることができます。 クラウド ファイル API に最も関心のあるドライバーは、ウイルス対策ファイル システム フィルターです。

ファイル システム ミニフィルター ドライバーは、フィルター マネージャーと呼ばれる特殊なカーネル モード コンポーネントによって管理およびサポートされます。 他の多くの業務の中でも、フィルター マネージャーは、フィルター メッセージ ポートと呼ばれるコンストラクトを介して、フィルターとユーザー モード コンポーネント間のフィルターなしの通信を容易にします。

ハイドレーション ポリシー

Windows では、さまざまな プライマリ ハイドレーション ポリシー と セカンダリ ハイドレーション ポリシー 修飾子がサポートされています。 プライマリハイドレーション ポリシーの順序は次のとおりです。

常にフル > フル > プログレッシブ > 部分的

アプリケーションと同期エンジンの両方で、優先されるプライマリ ハイドレーション ポリシーを定義できます。 指定しない場合、既定のハイドレーション ポリシーは、アプリケーションと同期エンジンの両方に対してプログレッシブです。

クラウド ファイルのハイドレーション ポリシーは、次の式によってファイルを開く時点で決定されます。

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

たとえば、ユーザーが Contoso PDF Viewer を使用して Fabrikam Cloud Drive に保存されている PDF ファイルを開こうとしているとします。これは、優先ハイドレーション ポリシーを指定しません。 そのため、アプリケーションハイドレーション ポリシーはプログレッシブ ハイドレーションです(この場合は既定)。 ただし、Fabrikam Cloud Drive は完全ハイドレーション同期エンジンであるため、ファイルの最終的なハイドレーション ポリシーは完全ハイドレーションになり、最初のアクセス時にファイルが完全にハイドレートされます。 同期エンジンがプログレッシブハイドレートをサポートしているが、アプリのユーザー設定が完全ハイドレートである場合も、同じ結果が発生します。

ファイルを開いた後は、ファイルハイドレーション ポリシーを変更できないことに注意してください。

再解析ポイントを使用するアプリケーションとの互換性

クラウド ファイル API は、 再解析ポイントを使用してプレースホルダー システムを実装します。 再解析ポイントに関する一般的な誤解は、それらがシンボリック リンクと同じであるという点です。 この誤解はアプリケーションの実装に反映されることがあり、その結果、多くの既存のアプリケーションで再解析ポイントが発生したときにエラーが発生します。

互換性の問題を軽減するために、クラウドファイルAPIは、メインイメージが%systemroot%の下にある同期エンジンとプロセスを除いたすべてのアプリケーションから、再解析ポイントを常に非表示にします。 再解析ポイントを正しく理解しているアプリケーションは、RtlSetProcessPlaceholderCompatibilityMode または RtlSetThreadProcessPlaceholderCompatibilityMode を使用して、プラットフォームがクラウドファイルAPIの再解析ポイントを公開することを強制できます。

クラウド ファイル検索は、Windows 11 バージョン 24H2 以降の Copilot+ PC でサポートされています。 クラウド ストレージ プロバイダーが Windows Search エクスペリエンスと統合するには、次の機能を使用できます。

  • クラウド ストレージ プロバイダーは、同期ルートのファイル検索ハンドラーを登録して、エクスプローラーと Windows Search に検索結果を投稿できるようにします。
  • クラウド ストレージ プロバイダーは、同期ルート レジストリ キーの 下にある SearchHandlerFactory レジストリ値を COM ローカル サーバー オブジェクトの CLSID に設定することで、検索ハンドラーを登録します。 このローカル サーバー オブジェクトは、 IStorageProviderSearchHandlerFactory インターフェイスを 実装します。
  • IStorageProviderSearchHandlerFactory は、IStorageProviderSearchHandler の実装を作成します。 この IStorageProviderSearchHandler 実装は、クラウド プロバイダーの検索サービスを呼び出して、デバイスでローカルに使用できない可能性があるファイルを検索します。
  • Windows Search エクスペリエンスは、検索中に Find メソッドを呼び出し、その結果をローカル検索インデクサーの結果とマージします。

関連コンテンツ

クラウド ファイル プロバイダーと Windows Search の統合

IStorageProviderSearchHandlerFactory

Windows.Storage.Provider 名前空間