Erstellen eines Cloud-Synchronisierungsmoduls, das Platzhalterdateien unterstützt

Ein Synchronisierungsmodul ist ein Dienst, der Dateien synchronisiert, in der Regel zwischen einem Remotehost und einem lokalen Client. Synchronisierungsmodule unter Windows stellen diese Dateien häufig über das Windows-Dateisystem und den Datei-Explorer für den Benutzer bereit. Vor Windows 10, Version 1709, war die Unterstützung des Synchronisierungsmoduls in Windows auf szenarioagnostische Ad-hoc-Oberflächen wie den Navigationsbereich des Datei-Explorers, die Windows-Taskleiste und (für weitere technische Anwendungen) Dateisystemfiltertreiber beschränkt.

Windows 10, Version 1709 (auch als Fall Creators Update bezeichnet), führte die Clouddateien-API ein. Diese API ist eine neue Plattform, die die Unterstützung für Synchronisierungsmodule formalisiert. Die Clouddateien-API bietet Unterstützung für Synchronisierungsmodule auf eine Weise, die Entwicklern und Endbenutzern viele neue Vorteile bietet.

Die Clouddateien-API enthält die folgenden systemeigenen Win32-APIs und Windows-Runtime-APIs (WinRT):

• Cloudfilter-API: Diese native Win32-API bietet Funktionen an der Grenze zwischen dem Benutzermodus und dem Dateisystem. Diese API behandelt die Erstellung und Verwaltung von Platzhalterdateien und Verzeichnissen.
• Windows.Storage.Provider-Namespace: Mit dieser WinRT-API können Anwendungen den Cloudspeicheranbieter konfigurieren und den Synchronisierungsstamm beim Betriebssystem registrieren.

Unterstützte Funktionen

Die Clouddateien-API bietet die folgenden Features zum Erstellen von Cloudsynchronisierungsmodulen.

Platzhalterdateien

• Synchronisierungsmodule können Platzhalterdateien erstellen, die nur 1 KB Speicherplatz für den Dateisystemheader verbrauchen und die automatisch unter normalen Nutzungsbedingungen in vollständige Dateien hydratisiert werden. Platzhalterdateien, die als typische Dateien für Apps und endbenutzer in der Windows-Shell vorhanden sind.
• Platzhalterdateien werden vertikal vom Windows-Kernel bis zur Windows-Shell integriert, und die App-Kompatibilität mit Platzhalterdateien ist in der Regel ein Nichtproblem. Unabhängig davon, ob Sie Dateisystem-APIs, die Eingabeaufforderung oder eine Desktop- oder UWP-App für den Zugriff auf eine Platzhalterdatei verwenden, wird die Datei ohne zusätzliche Codeänderungen hydratisiert, und diese App kann die Datei normal verwenden.
• Dateien können in drei Zuständen vorhanden sein:
  • Platzhalterdatei: Eine leere Darstellung der Datei und nur verfügbar, wenn der Synchronisierungsdienst verfügbar ist.
  • Vollständige Datei: Die Datei wurde implizit hydratisiert und kann vom System dehydratisiert werden, wenn Speicherplatz erforderlich ist.
  • Vollständige Datei angeheftet: Die Datei wurde explizit vom Benutzer über den Datei-Explorer hydratisiert und ist garantiert offline verfügbar.

In der folgenden Abbildung wird veranschaulicht, wie der Platzhalter, die vollständigen und angehefteten Dateizustände im Datei-Explorer angezeigt werden.

Standardisierte Synchronisierungsstammregistrierung

• Das Registrieren eines Synchronisierungs-Stamms ist einfach und standardisiert. Dazu gehört die Erstellung eines brandingierten Knotens im Navigationsbereich des Datei-Explorers, wie im folgenden Screenshot gezeigt. Wurzeln können entweder als einzelne Einträge auf oberster Ebene oder als untergeordnete Elemente einer übergeordneten Gruppierung erstellt werden.

  

Shell-Integration

• Statussymbole:
  • Die Clouddateien-API stellt standardisierte, automatische Hydratationsstatussymbole bereit, die im Datei-Explorer und auf dem Windows-Desktop angezeigt werden.
  • Zusätzlich zu den standardmäßigen Windows-Zustandssymbolen, die für den Hydratationszustand verwendet werden, können Sie benutzerdefinierte Zustandssymbole für zusätzliche dienstspezifische Eigenschaften bereitstellen.
  • Ersetzt Legacy-Symbolüberlagerungs-Shell-Erweiterungen.
• Fortschrittsanzeige:
  • Beim Öffnen einer Platzhalterdatei, deren Hydratisierung mehr als ein paar Sekunden dauert, wird der Hydratisierungsfortschritt angezeigt. Der Fortschritt wird an einigen Stellen je nach Kontext angezeigt:
    • In einem Dialogfenster der Kopier-Engine.
    • Der Inlinefortschritt wird neben der Datei im Datei-Explorer angezeigt.
    • Wenn die Datei nicht auf ausdrückliche Anweisung des Benutzers geöffnet wird, wird eine Toastbenachrichtigung angezeigt, um den Benutzer zu informieren und eine Möglichkeit zur Steuerung unbeabsichtigter Hydratationsaktivität bereitzustellen.
• Miniaturansichten und Metadaten:
  • Platzhalterdateien können umfangreiche, vom Dienst bereitgestellte Miniaturansichten und erweiterte Dateimetadaten aufweisen, um dem Benutzer eine nahtlose Datei-Explorer-Erfahrung zu bieten.
• Navigationsbereich des Datei-Explorers:
  • Das Registrieren eines Synchronisierungsstamms mit der Clouddateien-API bewirkt, dass der Synchronisierungsstamm (mit einem Symbol und benutzerdefiniertem Namen) im Navigationsbereich des Datei-Explorers angezeigt wird.
• Kontextmenüs des Datei-Explorers:
  • Das Registrieren eines Synchronisierungsstamms mit der Clouddateien-API stellt automatisch mehrere Verben (Menüeinträge) im Kontextmenü des Datei-Explorers bereit, mit denen der Benutzer den Hydratationsstatus seiner Datei steuern kann.
  • Zusätzliche Verben können diesem Abschnitt des Kontextmenüs mithilfe von Desktop Bridge-kompatiblen APIs hinzugefügt werden.
• Benutzersteuerung der Dateihydratation:
  • Benutzer haben immer die Kontrolle über die Dateihydratation, auch wenn die Dateien nicht explizit vom Benutzer hydratisiert werden. Eine interaktive Toast-Benachrichtigung wird für die Hintergrundaktualisierung angezeigt, um den Benutzer zu informieren und Auswahlmöglichkeiten anzubieten. Die folgende Abbildung zeigt eine Popupbenachrichtigung für eine hydratisierende Datei.
  • Wenn ein Benutzer eine App daran hindert, Dateien über ein interaktives Popup zu hydratisieren, können sie die Blockierung der App auf der Seite "Automatische Dateidownloads " in den Einstellungen aufheben.
• Kopieren von Copy-Engine-Operationen (unterstützt in Windows 10 Insider Preview Build 19624 und späteren Versionen):
  • Cloudspeicheranbieter können einen Shellkopie-Hook registrieren, um Dateivorgänge innerhalb ihres Synchronisierungsstamms zu überwachen.
  • Der Anbieter registriert seinen Kopierhaken, indem er den CopyHook-Registrierungswert unter dem Synchronisierungsstammregistrierungsschlüssel auf die CLSID des lokalen COM-Serverobjekts festlegt. Dieses lokale Serverobjekt implementiert die IStorageProviderCopyHook-Schnittstelle .
• Dateifreigabe (unterstützt in Windows 11, Version 21H2 und höher):
  • Cloudspeicheranbieter können einen Freigabeverwalter registrieren, der aufgerufen wird, wenn der Benutzer in einer Clouddatei den Befehl "Freigeben" innerhalb seines Synchronisierungsstamms auswählt.
  • Der Anbieter registriert seinen Freigabehandler, indem er den ShareHandler-Registrierungswert unter dem Sync-Root-Registrierungsschlüssel auf die CLSID des lokalen COM-Serverobjekts festlegt. Dieses lokale Serverobjekt implementiert die IExplorerCommand-Schnittstelle .

Desktop-Brücke

• Synchronisierungsmodule mit den Clouddateien-APIs sind für die Verwendung der Desktop-Brücke als Implementierungsanforderung konzipiert.

Cloud Mirror-Beispiel

Im Cloud Mirror-Beispiel wird veranschaulicht, wie Sie eine Lösung erstellen, die die Clouddateien-API verwendet. Sie soll nicht als Produktionscode verwendet werden. Es fehlt an robuster Fehlerbehandlung und es ist so leicht zu verstehen wie möglich geschrieben. Es wird Als Cloud Mirror bezeichnet, da er einfach einen lokalen Ordner auf Ihrem lokalen Datenträger spiegelt. Sie geben einen Serverordner an, der Ihren Clouddateienserver und einen Clientordner darstellt, der den Synchronisierungsstammpfad angeben soll. Ein Knoten auf oberster Ebene wird im Navigationsbereich im Datei-Explorer namens TestStorageProviderDisplayName angezeigt, und dieser Knoten wird dem angegebenen Clientordner zugeordnet.

Bei der Synchronisierung sind dies die Dinge, die ein vollständig entwickelter Clouddateien-Synchronisierungsanbieter implementieren muss:

• Wenn die Synchronisierungsstammdatei nur ein Platzhalter ist, ist der Dienst für das Kopieren des Inhalts der Datei für die Hydratation verantwortlich. Dies wird im Beispiel implementiert.
• Wenn es sich bei der Synchronisierungsstammdatei um eine vollständige Datei handelt und der Inhalt der Datei im Clouddienst geändert wird, ist der Dienst dafür verantwortlich, den lokalen Synchronisierungsclient über die Änderung zu informieren, und der lokale Synchronisierungsclient muss Zusammenführungen gemäß ihren eigenen Spezifikationen verarbeiten. Dies ist im Beispiel nicht implementiert.
• Wenn die Synchronisierungsstammdatei eine vollständige Datei ist und sich der Inhalt der Datei im Synchronisierungsstammpfad (lokaler Client) ändert, muss der lokale Synchronisierungsclient den Clouddienst benachrichtigen und Zusammenführungen gemäß den eigenen Spezifikationen durchführen. Die Benachrichtigung zur Änderung der lokalen Datei wird im Beispiel implementiert, führt aber keine Aktion aus.

Verwenden Sie das Beispiel

1. Erstellen Sie zwei Ordner auf der lokalen Festplatte. Einer von ihnen fungiert als Server und der andere als Client.
2. Fügen Sie dem Serverordner einige Dateien hinzu. Stellen Sie sicher, dass der Clientordner leer ist.
3. Öffnen Sie das Cloud Mirror-Beispiel in Visual Studio. Legen Sie das CloudMirrorPackage-Projekt als Startprojekt fest, und erstellen Sie dann das Beispiel, und führen Sie es aus. Wenn Sie vom Beispiel dazu aufgefordert werden, geben Sie die beiden Pfade zu Ihren Server- und Clientordnern ein. Danach wird ein Konsolenfenster mit Diagnoseinformationen angezeigt.
4. Öffnen Sie den Datei-Explorer, und vergewissern Sie sich, dass der Knoten "TestStorageProviderDisplayName " und die Platzhalter für alle Dateien angezeigt werden, die Sie in den Serverordner kopiert haben. Um eine Anwendung zu simulieren, die versucht, Dateien zu öffnen, ohne die Auswahl zu verwenden, kopieren Sie mehrere Bilder in den Serverordner. Doppelklicken Sie in Ihrem Synchronisierungsstammordner auf einen dieser Ordner, und vergewissern Sie sich, dass sie hydratisiert wird. Öffnen Sie dann die Fotos-App. Die App lädt benachbarte Dateien im Hintergrund vorab, damit es unwahrscheinlicher wird, dass der Nutzer beim Durchsuchen der anderen Bilder Verzögerungen erlebt. Sie können die Hintergrund-Dehydrierung über Toasts oder im Datei-Explorer beobachten.
5. Klicken Sie im Datei-Explorer mit der rechten Maustaste auf eine Datei, um ein Kontextmenü anzuzeigen, und bestätigen Sie, dass das Menüelement "TestCommand " angezeigt wird. Wenn Sie auf dieses Menüelement klicken, wird ein Meldungsfeld angezeigt.
6. Um das Beispiel zu beenden, richten Sie den Fokus auf die Konsolenausgabe und drücken Sie STRG-C. Dadurch wird die Synchronisierungsstammregistrierung bereinigt, sodass der Anbieter deinstalliert wird. Wenn das Beispiel abstürzt, ist es möglich, dass der Synchronisierungsstamm registriert bleibt. Dadurch wird der Datei-Explorer jedes Mal neu gestartet, wenn Sie auf etwas klicken, und Sie werden aufgefordert, die gefälschten Client- und Serverspeicherorte einzugeben. Deinstallieren Sie in diesem Fall die CloudMirrorPackage-Beispielanwendung von Ihrem Computer.

Beispielarchitektur

Das Beispiel ist bewusst einfach. Es verwendet statische Klassen, um das Übergeben von Instanzzeigern unnötig zu machen. Dies sind die Hauptklassen im Beispiel:

• FakeCloudProvider: Diese Klasse auf oberster Ebene steuert die folgenden Arbeitsklassen:
  • CloudProviderRegistrar: Registriert die Synchronisierungsstamminformationen mit der Windows-Shell.
  • Platzhalter: Generiert die Platzhalterdateien im Synchronisierungsstammpfad.
  • ShellServices: Erstellt die Windows Shell-Anbieter für das Kontextmenü, Miniaturansichten und andere Dienste.
  • CloudProviderSyncRootWatcher: Instanziiert ein DirectoryWatcher, um Änderungen am Synchronisierungsstammpfad zu überwachen und auf Änderungen zu reagieren.
  • FileCopierWithProgress: Kopiert Dateien aus dem Serverordner langsam in Den Clientordner, um das Herunterladen von Dateien von einem echten Cloudserver zu simulieren. Stellt Fortschrittsanzeigen bereit, sodass Benachrichtigungen und der Datei-Explorer dem Benutzer etwas Informatives anzeigen.

Zusätzlich zu den obigen Klassen bietet das Beispiel auch mehrere Hilfsklassen, um den Benutzer zur Eingabe von Ordnern und einigen Hilfsprogrammen aufzufordern. Der TestExplorerCommandHandler, CustomStateProvider, ThumbnailProvider und UriSource sind alle Beispiele für Shell-Dienstanbieter.

Api-Architektur für Clouddateien

Im Kern des Speicherstapels in der Clouddateien-API ist ein Dateisystem-Minifiltertreiber namens cldflt.sys. Dieser Treiber fungiert als Proxy zwischen den Anwendungen des Benutzers und dem Synchronisierungsmodul. Ihr Synchronisierungsmodul weiß, wie die Daten bei Bedarf heruntergeladen und hochgeladen werden, während es für cldflt.sys verantwortlich ist, mit der Shell Dateien so zu präsentieren, als ob die Clouddaten lokal verfügbar sind.

Cldflt.sys unterstützt derzeit nur NTFS-Volumes, da sie von einigen für NTFS eindeutigen Features abhängt.

Es gibt viele Dateisystem-Minifiltertreiber in einem System, und sie können gleichzeitig auf einem bestimmten Volume aktiv sein. Die Treiber, die für die Cloud-Dateien-API am meisten interessant sind, sind die Antiviren-Dateisystemfilter.

Dateisystem-Minifiltertreiber werden von einer speziellen Kernelmoduskomponente verwaltet und unterstützt, die als Filter-Manager bezeichnet wird. Unter vielen anderen Aufgaben erleichtert der Filtermanager die ungefilterte Kommunikation zwischen Filtern und Benutzermoduskomponenten über ein Konstrukt, das als Filternachrichtenport bezeichnet wird.

Hydratationsrichtlinien

Windows unterstützt eine Vielzahl von primären Hydratationsrichtlinien und modifizierer für sekundäre Hydratationsrichtlinien . Primäre Hydratationsrichtlinien haben folgende Reihenfolge:

Immer voll > Voll > Progressiv > Teilweise

Sowohl Anwendungen als auch Synchronisierungsmodule können ihre bevorzugte primäre Hydratationsrichtlinie definieren. Wenn nicht angegeben, ist die standardmäßige Hydratationsrichtlinie für Anwendungen und Synchronisierungs-Engines progressiv.

Die Hydratationsrichtlinie einer Clouddatei wird zum Zeitpunkt des Öffnens der Datei durch diese Formel bestimmt:

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

Nehmen wir beispielsweise an, der Benutzer versucht, eine AUF Fabrikam Cloud Drive gespeicherte PDF-Datei mit Contoso PDF Viewer zu öffnen, die keine bevorzugte Hydratationsrichtlinie angibt. Die Anwendungshydratationsrichtlinie ist daher eine progressive Hydratation, hierbei standardmäßig. Da Fabrikam Cloud Drive jedoch ein vollständiges Synchronisierungsmodul ist, wird die endgültige Hydratationsrichtlinie für die Datei zu einer vollständigen Hydratation, was dazu führt, dass die Datei beim ersten Zugriff vollständig hydratisiert wird. Dasselbe Ergebnis tritt in Fällen auf, in denen das Synchronisierungsmodul die progressive Hydratation unterstützt, die App jedoch eine volle Hydratation bevorzugt.

Beachten Sie, dass die Dateihydratationsrichtlinie nach dem Öffnen der Datei nicht mehr geändert werden kann.

Kompatibilität mit Anwendungen, die Umleitungspunkte verwenden

Die Clouddateien-API implementiert das Platzhaltersystem mithilfe von Umleitungspunkten. Ein häufiges Missverständnis über Analysepunkte besteht darin, dass sie mit symbolischen Verknüpfungen identisch sind. Diese Fehleinschätzung spiegelt sich gelegentlich in Anwendungsimplementierungen wider, was zur Folge hat, dass viele bestehende Anwendungen bei jedem Umleitungspunkt auf Fehler stoßen.

Um dieses Kompatibilitätsproblem zu beheben, blendet die Clouddateien-API immer ihre Analysepunkte aus allen Anwendungen mit Ausnahme von Synchronisierungsmodulen und Prozessen aus, deren Hauptbild sich unter %systemroot%befindet. Anwendungen, die Reparsepunkte richtig verstehen, können die Plattform zwingen, Cloud-Dateien-API-Reparsepunkte mithilfe von RtlSetProcessPlaceholderCompatibilityMode oder RtlSetThreadProcessPlaceholderCompatibilityMode verfügbar zu machen.

Suche nach Clouddateien

Die Suche nach Clouddateien wird in Windows 11, Version 24H2 und höher auf Copilot+ PCs oder KI-fähigen Cloud-PCs unterstützt. Die folgenden Features sind für Cloudspeicheranbieter verfügbar, die in die Windows Search-Umgebung integriert werden können:

• Cloudspeicheranbieter können einen Dateisuchhandler für ihren Synchronisierungsstamm registrieren, sodass sie Suchergebnisse zum Datei-Explorer und zur Windows-Suche beitragen können.
• Cloudspeicheranbieter registrieren einen Suchhandler, indem Sie den SearchHandlerFactory-Registrierungswert unter ihrem Synchronisierungsstammregistrierungsschlüssel auf die CLSID des lokalen COM-Serverobjekts festlegen. Dieses lokale Serverobjekt implementiert die IStorageProviderSearchHandlerFactory-Schnittstelle .
• Die IStorageProviderSearchHandlerFactory erstellt eine Implementierung von IStorageProviderSearchHandler. Diese IStorageProviderSearchHandler-Implementierung ruft den Suchdienst des Cloudanbieters auf, um Dateien zu durchsuchen, die möglicherweise nicht lokal auf dem Gerät verfügbar sind.
• Die Windows Search-Oberfläche ruft die Find-Methode während einer Suche auf und führt die Ergebnisse mit denen aus dem lokalen Suchindexer zusammen.

Verwandte Inhalte

Integration des Clouddateienanbieters in Windows Search

IStorageProviderSearchHandlerFactory

Windows.Storage.Provider-Namespace