Een cloudsynchronisatie-engine bouwen die tijdelijke aanduidingen voor bestanden ondersteunt

Een synchronisatie-engine is een service die bestanden synchroniseert, meestal tussen een externe host en een lokale client. Synchronisatie-engines in Windows presenteren deze bestanden vaak aan de gebruiker via het Windows-bestandssysteem en Verkenner. Vóór Windows 10, versie 1709, was de ondersteuning van de synchronisatie-engine in Windows beperkt tot scenarioagnostische ad-hocoppervlakken, zoals het navigatiedeelvenster van Verkenner, het Systeemvak van Windows en (voor meer technische toepassingen) stuurprogramma's voor bestandssysteemfilters.

Windows 10 versie 1709 (ook wel de Fall Creators Update genoemd) heeft de API voor cloudbestanden geïntroduceerd. Deze API is een nieuw platform dat ondersteuning voor synchronisatie-engines formaliseert. De API voor cloudbestanden biedt ondersteuning voor synchronisatie-engines op een manier die veel nieuwe voordelen biedt voor ontwikkelaars en eindgebruikers.

De CLOUDbestanden-API bevat de volgende systeemeigen Win32-API's en WinRT-API's (Windows Runtime):

• Cloudfilter-API: Deze systeemeigen Win32-API biedt functionaliteit op de grens tussen de gebruikersmodus en het bestandssysteem. Deze API verwerkt het maken en beheren van tijdelijke aanduidingen voor bestanden en mappen.
• Windows.Storage.Provider-naamruimte: met deze WinRT-API kunnen toepassingen de cloudopslagprovider configureren en de synchronisatiehoofdmap registreren bij het besturingssysteem.

Opmerking

De cloudbestanden-API biedt momenteel geen ondersteuning voor het implementeren van cloudsynchronisatie-engines in UWP-apps. Cloudsynchronisatie-engines moeten worden geïmplementeerd in desktop-apps.

Ondersteunde functies

De API voor cloudbestanden biedt de volgende functies voor het bouwen van cloudsynchronisatie-engines.

Tijdelijke aanduidingen voor bestanden

• Synchronisatie-engines kunnen plaatsaanduidingsbestanden maken die slechts 1 kB opslagruimte verbruiken voor de header van het bestandssysteem en die automatisch worden omgezet naar volledige bestanden onder normale gebruiksomstandigheden. Placeholder-bestanden worden gepresenteerd als typische bestanden voor apps en eindgebruikers in de Windows Shell.
• Tijdelijke aanduidingen voor bestanden worden verticaal geïntegreerd vanuit de Windows-kernel tot de Windows Shell en app-compatibiliteit met tijdelijke aanduidingenbestanden is doorgaans een niet-probleem. Of u nu bestandssysteem-API's, de opdrachtprompt of een desktop- of UWP-app gebruikt voor toegang tot een plaatsaanduidingsbestand, het bestand wordt gehydrateerd zonder extra codewijzigingen, en die app kan het bestand normaal gebruiken.
• Bestanden kunnen bestaan in drie toestanden:
  • Tijdelijke aanduiding voor bestand: een lege weergave van het bestand en alleen beschikbaar als de synchronisatieservice beschikbaar is.
  • Volledig bestand: het bestand is impliciet gehydrateerd en kan door het systeem worden gedehydrateerd als er ruimte nodig is.
  • Vastgezet volledig bestand: Het bestand is expliciet gedownload door de gebruiker via de Verkenner en is gegarandeerd offline beschikbaar.

In de volgende afbeelding ziet u hoe de tijdelijke aanduiding, volledige en vastgemaakte volledige bestandsstatussen worden weergegeven in Verkenner.

Gestandaardiseerde synchronisatiehoofdregistratie

• Het registreren van een synchronisatiewortel is eenvoudig en gestandaardiseerd. Dit omvat het maken van een merkknooppunt in het navigatiedeelvenster van Verkenner, zoals wordt weergegeven in de volgende schermopname. Wortels kunnen worden gemaakt als individuele topniveau-invoeringen, of als onderliggende onderdelen van een bovenliggende groep.

  

Shell-integratie

• Statuspictogrammen:
  • De API voor cloudbestanden biedt gestandaardiseerde, automatische hydratatiestatuspictogrammen die worden weergegeven in Verkenner en op het Windows-bureaublad.
  • Naast de standaardpictogrammen voor Windows-statussen die worden gebruikt voor hydratatiestatus, kunt u aangepaste statuspictogrammen opgeven voor aanvullende servicespecifieke eigenschappen.
  • Vervangt verouderde Shell-extensies voor overlay-pictogrammen.
• Voortgangsindicatie:
  • Als u een tijdelijke aanduiding opent die langer dan een paar seconden in beslag neemt, wordt de hydratatievoortgang weergegeven. De voortgang wordt op een aantal locaties weergegeven, afhankelijk van de context:
    • In een dialoogvenster van de kopieer-engine.
    • Inlinevoortgang wordt weergegeven naast het bestand in Verkenner.
    • Als het bestand niet wordt geopend volgens de specifieke instructie van de gebruiker, wordt een toastmelding weergegeven om de gebruiker te informeren en ervoor te zorgen dat onbedoelde hydratatieactiviteit beheerd kan worden.
• Miniaturen en metagegevens:
  • Placeholder-bestanden kunnen rijke door de service aangeboden miniaturen en uitgebreide bestandsmetagegevens hebben om de gebruiker een soepele Verkenner-ervaring te bieden.
• Navigatiedeelvenster van Verkenner:
  • Het registreren van een synchronisatiehoofdmap met de API voor cloudbestanden zorgt ervoor dat deze hoofdmap (met een pictogram en aangepaste naam) verschijnt in het navigatievenster van Verkenner.
• Contextmenu’s van Windows Verkenner
  • Het registreren van een synchronisatieroot met de cloud-file API biedt automatisch verschillende menu-opties in het contextmenu van Bestandsbeheer waarmee de gebruiker de hydratatiestatus van hun bestand kan beheren.
  • Aanvullende werkwoorden kunnen worden toegevoegd aan deze sectie van het contextmenu met behulp van Desktop Bridge-compatibele API's.
• Gebruikerscontrole over bestandshydratatie
  • Gebruikers hebben altijd controle over bestandshydratatie, zelfs wanneer de bestanden niet expliciet door de gebruiker worden gehydrateerd. Er wordt een interactieve pop-up weergegeven voor achtergrondhydratatie om de gebruiker te waarschuwen en opties te bieden. In de volgende afbeelding ziet u een pop-upmelding voor een hydraterend bestand.
  • Als een gebruiker blokkeert dat een app bestanden hydrateert via een interactieve pop-up, kan deze de blokkering van de app opheffen op de pagina Automatisch downloaden van bestanden in Instellingen.
• Kopieer-enginebewerkingen koppelen (ondersteund in Windows 10 Insider Preview Build 19624 en latere versies):
  • Cloudopslagproviders kunnen een shell-copy hook registreren om bestandsbewerkingen binnen hun synchronisatiewortel te monitoren.
  • De provider registreert de kopieerhook door de CopyHook-registerwaarde in te stellen onder hun synchronisatiehoofdsleutel naar de CLSID van hun lokale COM-serverobject. Met dit lokale serverobject wordt de IStorageProviderCopyHook-interface geïmplementeerd.
• Bestandsdeling (ondersteund in Windows 11 versie 21H2 en nieuwere versies):
  • Cloudopslagproviders kunnen een sharehandler registreren die wordt aangeroepen wanneer de gebruiker de opdracht Delen selecteert in een cloudbestand onder de synchronisatiehoofdmap.
  • De provider registreert hun share handler door de registerwaarde ShareHandler in te stellen onder hun synchronisatierootregistersleutel naar de CLSID van het lokale COM-serverobject. Met dit lokale serverobject wordt de interface IExplorerCommand geïmplementeerd.

Bureaubladbrug

• Synchronisatie-engines die gebruikmaken van de API's voor cloudbestanden, zijn ontworpen om de Desktop Bridge als implementatievereiste te gebruiken.

Voorbeeld van cloudspiegeling

Het cloudspiegelvoorbeeld laat zien hoe u een oplossing bouwt die gebruikmaakt van de API voor cloudbestanden. Het is niet bedoeld om te worden gebruikt als productiecode. Het ontbreekt aan robuuste foutafhandeling en het is geschreven om zo gemakkelijk mogelijk te worden begrepen. Het heet Cloud Mirror omdat deze gewoon een lokale map op uw lokale schijf spiegelt. U geeft een servermap op die bedoeld is voor uw cloudbestandenserver en een clientmap die is bedoeld om het pad naar de synchronisatiehoofdmap op te geven. Er wordt een knooppunt op het hoogste niveau weergegeven in het navigatiedeelvenster in Verkenner met de naam TestStorageProviderDisplayName en dit knooppunt wordt toegewezen aan de opgegeven clientmap.

Als het gaat om synchroniseren, zijn dit de dingen die een volledig ontwikkelde cloudbestandensynchronisatieprovider moet implementeren:

• Wanneer het synchronisatiehoofdbestand slechts een tijdelijke aanduiding is, is de service verantwoordelijk voor het kopiëren van de inhoud van het bestand voor hydratatie. Dit wordt geïmplementeerd in het voorbeeld.
• Wanneer het hoofdbestand van de synchronisatie een volledig bestand is en de inhoud van het bestand in de cloudservice wordt gewijzigd, is de service verantwoordelijk voor het melden van de lokale synchronisatieclient van de wijziging en moet de lokale synchronisatieclient samenvoegingen afhandelen volgens hun eigen specificaties. Dit wordt niet geïmplementeerd in het voorbeeld.
• Wanneer het synchronisatiehoofdbestand een volledig bestand is en de inhoud van het bestand in het hoofdpad van de synchronisatie (de lokale client) verandert, moet de lokale synchronisatieclient de cloudservice op de hoogte stellen en samenvoegingen afhandelen op basis van hun eigen specificaties. De melding over het wijzigen van lokale bestanden wordt geïmplementeerd in het voorbeeld, maar er wordt niets gedaan.

Het voorbeeld gebruiken

1. Maak twee mappen op uw lokale harde schijf. Een van hen fungeert als de server en de andere als de client.
2. Voeg enkele bestanden toe aan de servermap. Zorg ervoor dat de clientmap leeg is.
3. Open het cloudspiegelvoorbeeld in Visual Studio. Stel het CloudMirrorPackage-project in als uw opstartproject en bouw en voer het voorbeeld uit. Wanneer u hierom wordt gevraagd, voert u de twee paden naar uw server en clientmappen in. Hierna ziet u een consolevenster met diagnostische gegevens.
4. Open Verkenner en controleer of u het knooppunt TestStorageProviderDisplayName en de tijdelijke aanduidingen ziet voor alle bestanden die u naar de servermap hebt gekopieerd. Als u een toepassing wilt simuleren die bestanden probeert te openen zonder de kiezer te gebruiken, kopieert u verschillende installatiekopieën naar de servermap. Dubbelklik op een van deze mappen in uw synchronisatiehoofdmap en bevestig dat deze hydrateert. Open vervolgens de app Foto's. De app laadt vooraf aangrenzende bestanden op de achtergrond, zodat de gebruiker waarschijnlijker geen vertragingen ondervindt bij het bekijken van de andere afbeeldingen. U kunt zien dat de achtergrond uitdroging plaatsvindt via toasts of in Verkenner.
5. Klik met de rechtermuisknop op een bestand in Verkenner om een contextmenu weer te geven en bevestig dat u de menuopdracht TestCommand ziet. Als u op dit menu-item klikt, wordt een berichtvak weergegeven.
6. Als u het voorbeeld wilt stoppen, stelt u de focus in op de console-uitvoer en drukt u op Ctrl-C. Hiermee wordt de synchronisatiebronregistratie opgeschoond, zodat de provider wordt gedeïnstalleerd. Als het voorbeeld vastloopt, is het mogelijk dat de synchronisatiehoofdmap geregistreerd blijft. Dit zorgt ervoor dat Verkenner telkens opnieuw wordt gestart wanneer u op iets klikt en u wordt gevraagd om de valse client- en serverlocaties. Als dit het geval is, verwijdert u de voorbeeldtoepassing CloudMirrorPackage van uw computer.

Voorbeeldarchitectuur

Het voorbeeld is opzettelijk eenvoudig. Er worden statische klassen gebruikt om het onnodig te maken om aanwijzers voor exemplaren door te geven. Dit zijn de belangrijkste klassen in het voorbeeld:

• FakeCloudProvider: Deze klasse op het hoogste niveau beheert de volgende werkrolklassen:
  • CloudProviderRegistrar: registreert de synchronisatierootinformatie met de Windows Shell.
  • Placeholder-bestanden: genereert de placeholder-bestanden in het synchronisatie rootpad.
  • ShellServices: hiermee worden de Windows Shell-providers samengesteld voor het contextmenu, miniaturen en andere services.
  • CloudProviderSyncRootWatcher: Instantieert een DirectoryWatcher om wijzigingen in het pad naar de synchronisatiehoofdmap te controleren en om te reageren op wijzigingen.
  • FileCopierWithProgress: Kopieert bestanden van de servermap naar de clientmap langzaam in segmenten om te simuleren dat ze van een echte cloudserver worden gedownload. Geeft een voortgangsindicatie zodat de gebruiker iets informatiefs ziet in de gebruikersinterface van toasts en Bestandsverkenner.

Naast de bovenstaande klassen biedt het voorbeeld ook verschillende helperklassen om de gebruiker te vragen naar mappen en enkele hulpprogramma's. De TestExplorerCommandHandler, CustomStateProvider, ThumbnailProvider en UriSource zijn allemaal voorbeelden van Shell-serviceproviders.

API-architectuur voor cloudbestanden

De kern van de opslagstack in de API voor cloudbestanden is een minifilterstuurprogramma voor het bestandssysteem dat cldflt.syswordt genoemd. Dit stuurprogramma fungeert als proxy tussen de toepassingen van de gebruiker en uw synchronisatie-engine. Uw synchronisatie-engine weet hoe u de gegevens op aanvraag kunt downloaden en uploaden, terwijl het de verantwoordelijkheid is van cldflt.sys om met de Shell te werken om bestanden te presenteren alsof de cloudgegevens lokaal beschikbaar waren.

Cldflt.sys ondersteunt momenteel alleen NTFS-volumes omdat deze afhankelijk is van bepaalde functies die uniek zijn voor NTFS.

Er zijn veel stuurprogramma's voor het bestandssysteem minifilters in een systeem en ze kunnen tegelijkertijd actief zijn op een bepaald volume. De stuurprogramma's die het meest van belang zijn voor de API voor cloudbestanden zijn de antivirusbestandssysteemfilters.

Stuurprogramma's voor minifilters van het bestandssysteem worden beheerd en ondersteund door een speciaal kernelmodusonderdeel met de naam filterbeheer. De filterbeheerder faciliteert onder andere niet-gefilterde communicatie tussen filters en onderdelen van de gebruikersmodus via een constructie die bekend staat als filterberichtpoort.

Hydratatiebeleid

Windows ondersteunt verschillende primaire hydratatiebeleidsregels en secundaire hydratatiebeleidsmodifiers . Primaire hydratatiebeleid heeft deze volgorde:

Altijd volledig > Volledig > Progressief > Gedeeltelijk

Zowel toepassingen als synchronisatie-engines kunnen hun voorkeursbeleid voor primaire hydratatie definiëren. Als dit niet is opgegeven, is het standaard hydratatiebeleid progressief voor zowel toepassingen als synchronisatie-engines.

Het hydratatiebeleid van een cloudbestand wordt bepaald op het tijdstip waarop het bestand is geopend door deze formule:

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

Stel dat de gebruiker probeert een PDF-bestand te openen dat is opgeslagen op Fabrikam Cloud Drive met behulp van Contoso PDF Viewer, waarmee geen voorkeursbeleid voor hydratatie wordt opgegeven. Het toepassingshydratatiebeleid is daarom progressieve hydratatie, standaard in dit geval. Omdat Fabrikam Cloud Drive een volledig hydratatiesynchronisatiemechanisme is, wordt het definitieve hydratatiebeleid van het bestand volledige hydratatie, waardoor het bestand volledig gehydrateerd wordt bij eerste toegang. Hetzelfde resultaat treedt op in gevallen waarin de synchronisatie-engine progressieve hydratatie ondersteunt, maar de voorkeur van de app volledig hydratatie is.

Houd er rekening mee dat het bestand hydratatiebeleid niet kan worden gewijzigd nadat het bestand is geopend.

Compatibiliteit met toepassingen die gebruikmaken van reparsepunten

De API voor cloudbestanden implementeert het tijdelijke aanduidingssysteem met behulp van reparsepunten. Een veelvoorkomend misvatting over reparsepunten is dat ze hetzelfde zijn als symbolische koppelingen. Deze misvatting wordt af en toe weerspiegeld in toepassingsimplementaties, waardoor veel bestaande toepassingen fouten ondervinden bij het tegenkomen van een reparsepunt.

Om dit compatibiliteitsprobleem te verhelpen, verbergt de API voor cloudbestanden altijd de reparsepunten voor alle toepassingen, met uitzondering van synchronisatie-engines en processen waarvan de hoofdafbeelding zich onder %systemroot% bevindt. Toepassingen die reparsepunten correct begrijpen, kunnen ervoor zorgen dat het platform api-reparsepunten voor cloudbestanden beschikbaar maakt met behulp van RtlSetProcessPlaceholderCompatibilityMode of RtlSetThreadProcessPlaceholderCompatibilityMode.

Zoeken naar cloudbestanden

Zoeken naar cloudbestanden wordt ondersteund in Windows 11, versie 24H2 en hoger op Copilot+-pc's of cloud-pc's met AI. De volgende functies zijn beschikbaar voor cloudopslagproviders die kunnen worden geïntegreerd met de Windows Search-ervaring:

• Cloudopslagproviders kunnen een bestandszoekhandler registreren voor hun synchronisatiehoofdmap, zodat ze zoekresultaten kunnen bijdragen aan Verkenner en Windows Search.
• Cloudopslagproviders registreren een zoekhandler door de registerwaarde SearchHandlerFactory in te stellen onder hun synchronisatiewortelregistersleutel naar de CLSID van hun lokale COM-serverobject. Met dit lokale serverobject wordt de interface IStorageProviderSearchHandlerFactory geïmplementeerd.
• De IStorageProviderSearchHandlerFactory maakt een implementatie van IStorageProviderSearchHandler. Deze IStorageProviderSearchHandler-implementatie roept de zoekservice van de cloudprovider aan om bestanden te zoeken die mogelijk niet lokaal beschikbaar zijn op het apparaat.
• De Windows Search-ervaring roept de methode Zoeken aan tijdens een zoekopdracht, waarbij de resultaten worden samengevoegd met de resultaten van de lokale zoekindexeerfunctie.

Verwante inhoud

Integratie van cloudbestandenprovider met Windows Search

IStorageProviderSearchHandlerFactory

Windows.Storage.Provider-naamruimte