Erstellen eines Synchronisierungsmoduls, die Platzhalterdateien unterstützt

Ein Synchronisierungsmodul ist ein Dienst, der Dateien synchronisiert – in der Regel zwischen einem Remotehost und einem lokalen Client. Synchronisierungsmodule unter Windows zeigen Benutzer*innen diese Dateien oft über das Windows-Dateisystem und den Datei-Explorer an. Vor Windows 10, Version 1709, war die Unterstützung des Synchronisierungsmoduls in Windows auf szenarioabhängige Ad-hoc-Oberflächen beschränkt, wie den Navigationsbereich des Datei-Explorers, die Windows-Systemleiste und (für technischere Anwendungen) Dateisystem-Filtertreiber.

Mit Windows 10 Version 1709 (auch Fall Creators Update genannt) wurde die Cloud Files API eingeführt. Diese API ist eine neue Plattform, die die Unterstützung für Synchronisierungsmodule formalisiert. Die Cloud Files API bietet Unterstützung für Synchronisierungsmodule in einer Weise, die Entwickler*innen und Endbenutzer*innen viele neue Vorteile bietet.

Die Cloud Files API enthält die folgenden nativen Win32-APIs und Windows-Runtime (WinRT) APIs:

• Cloud Filter API: Diese native Win32-API bietet Funktionen an der Grenze zwischen dem Benutzermodus und dem Dateisystem. Diese API dient der Erstellung und Verwaltung von Platzhalterdateien und -verzeichnissen.
• Windows.Storage.Provider-Namespace: Diese WinRT-API ermöglicht es Anwendungen, den Anbieter des Cloud-Speichers zu konfigurieren und den Synchronisierungsstamm beim Betriebssystem zu registrieren.

Hinweis

Die Cloud Files API unterstützt derzeit nicht die Implementierung von Cloud-Synchronisierungsmodulen in UWP-Apps. Cloud-Synchronisierungsmodule müssen in Desktop-Anwendungen implementiert werden.

Unterstützte Features

Die Cloud Files API bietet die folgenden Features zum Erstellen von Cloud-Synchronisierungsmodulen.

Platzhalterdateien

• Synchronisierungsmodule können Platzhalterdateien erstellen, die nur 1 KB Speicherplatz für den Dateisystem-Header verbrauchen und sich unter normalen Nutzungsbedingungen automatisch in vollständige Dateien verwandeln. Platzhalterdateien erscheinen als typische Dateien für Anwendungen und Endbenutzer*innen in der Windows Shell.
• Platzhalterdateien sind vertikal vom Windows-Kernel bis zur Windows Shell integriert, und die Kompatibilität von Anwendungen mit Platzhalterdateien ist im Allgemeinen kein Problem. Unabhängig davon, ob Sie Dateisystem-APIs, die Eingabeaufforderung oder eine Desktop- oder UWP-Anwendung verwenden, um auf eine Platzhalterdatei zuzugreifen, wird die Datei ohne zusätzliche Code-Änderungen aktualisiert und die Anwendung kann die Datei normal verwenden.
• Dateien können drei Zustände haben:
  • Platzhalterdatei: Eine leere Darstellung der Datei und nur verfügbar, wenn der Synchronisierungsdienst verfügbar ist.
  • Vollständige Datei: Die Datei wurde implizit aktualisiert und kann vom System erneut aktualisiert werden, wenn Platz benötigt wird.
  • Angeheftete vollständige Datei: Die Datei wurde vom Benutzer bzw. von der Benutzerin ausdrücklich über den Datei-Explorer aktualisiert und ist garantiert offline verfügbar.

Die folgende Abbildung zeigt, wie der Status von Platzhalter-, vollständigen und angehefteten vollständigen Dateien im Datei-Explorer angezeigt wird.

Standardisierte Synchronisierungsstammregistrierung

• Die Registrierung eines Synchronisationsstamms ist einfach und standardisiert. Dazu gehört die Erstellung eines gebrandeten Knotens im Navigationsbereich des Datei-Explorers, wie im folgenden Screenshot zu sehen ist. Stämme können entweder als einzelne Elemente der obersten Ebene oder als untergeordnete Elemente einer übergeordneten Gruppierung erstellt werden.

  

Shellintegration

• Zustandssymbole:
  • Die Cloud Files API bietet standardisierte, automatische Symbole für den Aktualisierungszustand, die im Datei-Explorer und auf dem Windows-Desktop angezeigt werden.
  • Zusätzlich zu den Windows-Standardsymbolen für den Aktualisierungszustand können Sie benutzerdefinierte Zustandssymbole für zusätzliche dienstspezifische Eigenschaften bereitstellen.
  • Ersetzt die Shell-Erweiterungen der alten Symbolüberlagerung.
• Statusanzeige:
  • Wenn Sie eine Platzhalterdatei öffnen, deren Aktualisierung mehr als ein paar Sekunden dauert, wird der Fortschritt der Aktualisierung angezeigt. Der Fortschritt wird je nach Kontext an einigen Stellen angezeigt:
    • In einem Dialogfeld des Kopiermoduls.
    • Der Inlinefortschritt wird neben der Datei im Datei-Explorer angezeigt.
    • Wenn die Datei nicht auf ausdrückliche Anweisung eines Benutzers bzw. einer Benutzerin geöffnet wird, wird eine Popupbenachrichtigung angezeigt, um den Benutzer bzw. die Benutzerin zu informieren und ihm bzw. ihr die Möglichkeit zu geben, die unbeabsichtigte Aktualisierung zu kontrollieren.
• Miniaturansichten und Metadaten:
  • Platzhalterdateien können mit umfangreichen, vom Dienst bereitgestellten Miniaturansichten und erweiterten Datei-Metadaten versehen werden, um dem Benutzer bzw. der Benutzerin ein nahtloses Datei-Explorer-Erlebnis zu bieten.
• Navigationsbereich des Datei-Explorers:
  • Wenn Sie einen Synchronisationsstamm mit der Cloud Files API registrieren, wird dieser Synchronisationsstamm (mit einem Symbol und einem benutzerdefinierten Namen) im Navigationsbereich des Datei-Explorers angezeigt.
• Kontextmenüs des Datei-Explorers:
  • Die Registrierung eines Synchronisierungsstamms mit der Cloud Files API bietet automatisch mehrere Menüelemente im Kontextmenü des Datei-Explorers, mit denen der Benutzer bzw. die Benutzerin den Aktualisierungsstatus einer Datei steuern kann.
  • Diesem Abschnitt des Kontextmenüs können über Desktop Bridge-kompatible APIs weitere Kontextmenüelemente hinzugefügt werden.
• Benutzersteuerung der Dateiaktualisierung:
  • Benutzer*innen haben immer die Kontrolle über die Aktualisierung von Dateien, auch wenn diese nicht explizit vom Benutzer bzw. von der Benutzerin aktiviert wurde. Ein interaktives Popup wird angezeigt, um den Benutzer bzw. die Benutzerin zu benachrichtigen und Optionen anzubieten. Das folgende Bild zeigt eine Popupbenachrichtigung für eine aktualisierende Datei.
  • Wenn ein*e Benutzer*in eine App für das Aktivieren von Dateien über ein interaktives Popup blockiert, kann die Blockierung für diese App auf der Seite Automatische Dateidownloads in den Einstellungen wieder aufgehoben werden.
• Hooking von Vorgängen des Kopiermoduls (unterstützt in Windows 10 Insider Preview Build 19624 und späteren Versionen):
  • Anbieter von Cloud-Speichern können einen Shellkopie-Hook zur Überwachung von Dateivorgängen in ihrem Synchronisationsstamm registrieren.
  • Der Anbieter registriert seinen Kopie-Hook, indem er den Registrierungswert CopyHook unter seinem Synchronisations-Stammschlüssel auf die CLSID seines lokalen COM-Serverobjekts festlegt. Dieses lokale Serverobjekt implementiert die Schnittstelle IStorageProviderCopyHook.
• Dateifreigabe (unterstützt in Windows 11 Version 21H2 und späteren Versionen):
  • Anbieter von Cloud-Speichern können einen Freigabe-Handler registrieren, der aufgerufen wird, wenn ein*e Benutzer*in den Befehl „Freigeben“ für eine Cloud-Datei im Synchronisierungsstamm auswählt.
  • Der Anbieter registriert seinen Freigabe-Handler, indem er den ShareHandler-Registrierungswert unter seinem Synchronisations-Stammschlüssel auf die CLSID seines lokalen COM-Serverobjekts festlegt. Dieses lokale Serverobjekt implementiert die Schnittstelle IExplorerCommand.

Desktop-Brücke

• Synchronisierungsmodule die die Cloud Files APIs verwenden, sind so konzipiert, dass sie die Desktop--Brücke als Implementierungsvoraussetzung verwenden.

Cloud Mirror-Beispiel

Im Cloud Mirror-Beispiel wird veranschaulicht, wie Sie eine Lösung erstellen, die die Cloud Files API verwendet. Es sollte nicht als Produktionscode verwendet werden. Es fehlt eine robuste Fehlerbehandlung und es ist so geschrieben, dass es so leicht wie möglich zu verstehen ist. Es wird Cloud Mirror genannt, weil es einfach einen lokalen Ordner auf Ihrer lokalen Festplatte spiegelt. Sie geben einen Server-Ordner an, der Ihren Cloud-Dateiserver repräsentieren soll, und einen Client-Ordner, der den Stammordner für die Synchronisierung angeben soll. Im Navigationsbereich des Datei-Explorers erscheint ein Knoten der obersten Ebene mit dem Namen TestStorageProviderDisplayName, der dem angegebenen Client-Ordner zugeordnet ist.

Bei der Synchronisierung müssen diese Dinge von einem ausgereiften Anbieter für die Synchronisierung von Cloud-Dateien implementiert werden:

• Wenn die Stammdatei der Synchronisierung nur ein Platzhalter ist, ist der Dienst dafür verantwortlich, den Inhalt der Datei für die Aktualisierung zu kopieren. Dies ist im Beispiel implementiert.
• Wenn es sich bei der Synchronisierungsstammdatei um eine vollständige Datei handelt und sich der Inhalt der Datei im Cloud-Dienst ändert, ist der Dienst dafür verantwortlich, den lokalen Synchronisierungsclient über die Änderung zu benachrichtigen, und der lokale Synchronisierungsclient muss Zusammenführungen gemäß seinen eigenen Spezifikationen behandeln. Dies ist im Beispiel nicht implementiert.
• Wenn es sich bei der Synchronisierungsstammdatei um eine vollständige Datei handelt und sich der Inhalt der Datei im Synchronisierungsstammverzeichnis (des lokalen Clients) ändert, muss der lokale Synchronisierungsclient den Clouddienst benachrichtigen und Zusammenführungen gemäß seinen eigenen Spezifikationen behandeln. Die Benachrichtigung über lokale Datei-Änderungen ist in dem Beispiel implementiert, aber sie bewirkt nichts.

Verwenden des Beispiels

1. Erstellen Sie zwei Ordner auf der lokalen Festplatte. Einer davon 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 Projekt CloudMirrorPackage 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 er aktualisiert wird. Öffnen Sie dann die Fotos-App. Die App lädt benachbarte Dateien im Hintergrund vor, so dass es beim Durchsehen der anderen Bilder kaum zu Verzögerungen kommt. Sie können die erneute Aktualisierung im Hintergrund über Popups oder im Datei-Explorer beobachten.
5. Klicken Sie mit der rechten Maustaste auf eine Datei im Datei-Explorer, um ein Kontextmenü aufzurufen, und stellen Sie sicher, dass Sie den Menüpunkt TestCommand sehen. Wenn Sie auf dieses Menüelement klicken, wird ein Nachrichtenfeld angezeigt.
6. Um das Beispiel zu beenden, gehen Sie 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 weiterhin registriert ist. Dies führt dazu, dass der Datei-Explorer jedes Mal neu gestartet wird, wenn Sie auf etwas klicken. Außerdem werden Sie zur Eingabe der simulierten Client- und Serverstandorte aufgefordert. Deinstallieren Sie in diesem Fall die Beispielanwendung CloudMirrorPackage von Ihrem Computer.

Beispielarchitektur

Das Beispiel ist bewusst einfach. Es werden statische Klassen verwendet, so dass keine Instanzzeiger übergeben werden müssen. Dies sind die Standard Klassen im Beispiel:

• FakeCloudProvider: Diese Klasse auf oberster Ebene steuert die folgenden Worker-Klassen:
  • CloudProviderRegistrar: Registriert die Synchronisierungsstamminformationen in der Windows Shell.
  • Placeholders: Generiert die Platzhalterdateien im Synchronisierungsstammpfad.
  • ShellServices: Erstellt die Windows Shell-Anbieter für das Kontextmenü, Miniaturansichten und andere Dienste.
  • CloudProviderSyncRootWatcher: Instanziiert einen DirectoryWatcher, um Änderungen am Synchronisierungsstammpfad zu überwachen und auf Änderungen zu reagieren.
  • FileCopierWithProgress: Kopiert Dateien aus dem Serverordner langsam in Blöcken in den Clientordner, um das Herunterladen von Dateien von einem echten Cloudserver zu simulieren. Stellt Statusanzeigen bereit, sodass Popups und Explorer UI dem Benutzer bzw. der Benutzerin etwas informatives zeigen.

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

Architektur der Cloud Files API

Kern des Speicherstapels in der Cloud Files API ist ein Dateisystem-Minifiltertreiber mit dem Namen cldflt.sys. Dieser Treiber fungiert als Proxy zwischen den Anwendungen von Benutzer*innen und Ihrem Synchronisierungsmodul. Ihr Synchronisierungsmodul weiß, wie die Daten bei Bedarf heruntergeladen und hochgeladen werden können, während es die Aufgabe von cldflt.sys ist, mit der Shell zusammenzuarbeiten, um die Dateien so darzustellen, als ob die Clouddaten lokal verfügbar wären.

Cldflt.sys unterstützt derzeit nur NTFS-Volumes, da es von einigen Features abhängig ist, die nur NTFS hat.

Es gibt viele Dateisystem-Minifiltertreiber in einem System, und sie können gleichzeitig auf einem bestimmten Volume aktiv sein. Die wichtigsten Treiber für die Cloud Files API sind die Anti-Virus-Dateisystemfilter.

Dateisystem-Minifiltertreiber werden von einer speziellen Kernelmodus-Komponente namens Filtermanager verwaltet und unterstützt. Neben vielen anderen Aufgaben erleichtert der Filtermanager die ungefilterte Kommunikation zwischen Filtern und Komponenten im Benutzermodus über ein Konstrukt, das als Filternachrichtenport bekannt ist.

Aktualisierungsrichtlinien

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

Immer vollständig > Vollständig > Progressiv > Partiell

Sowohl Anwendungen als auch Synchronisierungsmodule können ihre bevorzugte primäre Aktualisierungsrichtlinie definieren. Wenn nichts angegeben ist, ist „Progressiv“ die Standard-Aktualisierungsrichtlinie für Anwendungen und Synchronisierungsmodule.

Die Aktualisierungsrichtlinie 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, ein*e Benutzer*in versucht, eine im Fabrikam-Cloud Drive gespeicherte PDF-Datei mit Contoso PDF Viewer zu öffnen, für die keine bevorzugte Aktualisierungsrichtlinie angegeben wurde. In diesem Fall ist die Aktualisierungsrichtlinie der Anwendung daher standardmäßig die progressive Aktualisierung. Da der Fabrikam-Cloud Drive jedoch ein vollständiges Synchronisierungsmodul ist, wird die endgültige Aktualisierungsrichtlinie für die Datei zu einer „vollständigen“ Aktualisierung. Dies führt dazu, dass die Datei beim ersten Zugriff vollständig aktualisiert wird. Dasselbe Ergebnis tritt in Fällen auf, in denen das Synchronisierungsmodul die „progressive“ Aktualisierung unterstützt, die Einstellung der App jedoch die „vollständige“ Aktualisierung ist.

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

Kompatibilität mit Anwendungen, die Analysepunkte verwenden

Die Cloud Files API implementiert das Platzhaltersystem mithilfe von Analysepunkten. Analysepunkte werden häufig fälschlicherweise mit symbolischen Verknüpfungen gleichgesetzt. Dieses Missverständnis spiegelt sich gelegentlich in den Implementierungen von Anwendungen wider, so dass viele bestehende Anwendungen auf Fehler stoßen, wenn sie auf einen Analysepunkt stoßen.

Um dieses Kompatibilitätsproblem zu umgehen, verbirgt die Cloud Files API ihre Analysepunkte immer vor allen Anwendungen mit Ausnahme von Synchronisierungsmodulen und Prozessen, deren Haupt-Image sich unter %systemroot% befindet. Anwendungen, die Analysepunkte richtig verstehen, können die Plattform zwingen, Cloud Files API-Analysepunkte mithilfe von RtlSetProcessPlaceholderCompatibilityMode oder RtlSetThreadProcessPlaceholderCompatibilityMode verfügbar zu machen.