Vytvoření modulu cloudové synchronizace, který podporuje zástupné soubory

Synchronizační modul je služba, která synchronizuje soubory, obvykle mezi vzdáleným hostitelem a místním klientem. Synchronizační moduly ve Windows často představují tyto soubory uživateli prostřednictvím systému souborů Windows a Průzkumníka souborů. Před Windows 10 verze 1709 byla podpora synchronizačního modulu ve Windows omezena na plochy nezávislé na scénářích, jako je navigační podokno Průzkumníka souborů, hlavní panel systému Windows a (pro další technické aplikace) ovladače filtru systému souborů.

Windows 10 verze 1709 (označovaná také jako Fall Creators Update) zavedlo rozhraní API pro cloudové soubory. Toto rozhraní API je nová platforma, která formalizuje podporu synchronizačních modulů. Rozhraní API pro cloudové soubory poskytuje podporu synchronizačních modulů způsobem, který vývojářům a koncovým uživatelům nabízí mnoho nových výhod.

Rozhraní API pro cloudové soubory obsahuje následující nativní rozhraní API Win32 a rozhraní API prostředí Windows Runtime (WinRT):

• Rozhraní API cloudového filtru: Toto nativní rozhraní API Win32 poskytuje funkce na hranici mezi uživatelským režimem a systémem souborů. Toto rozhraní API zpracovává vytváření a správu zástupných souborů a adresářů.
• Obor názvů Windows.Storage.Provider: Toto rozhraní WINRT API umožňuje aplikacím konfigurovat poskytovatele cloudového úložiště a zaregistrovat kořen synchronizace s operačním systémem.

Poznámka:

Rozhraní API cloudových souborů v současné době nepodporuje implementaci cloudových synchronizačních modulů v aplikacích pro UPW. Moduly pro synchronizaci cloudu musí být implementovány v desktopových aplikacích.

Podporované funkce

Rozhraní API pro cloudové soubory poskytuje následující funkce pro vytváření cloudových synchronizačních modulů.

Zástupné soubory

• Synchronizační moduly můžou vytvářet zástupné soubory, které spotřebovávají pouze 1 kB úložiště pro hlavičku systému souborů a které automaticky hydratují do celých souborů za normálních podmínek použití. Zástupné soubory se v prostředí Windows Shell zobrazují jako typické soubory aplikacím a koncovým uživatelům.
• Zástupné soubory jsou svisle integrované z jádra Windows až po Windows Shell a kompatibilita aplikací se zástupnými soubory není obecně problém. Bez ohledu na to, jestli pro přístup k zástupného souboru používáte rozhraní API systému souborů, příkazový řádek nebo desktopovou aplikaci nebo aplikaci pro UWP, soubor se aktivuje bez dalších změn kódu a aplikace může soubor normálně používat.
• Soubory mohou existovat ve třech stavech:
  • Zástupný soubor: Prázdná reprezentace souboru a dostupná pouze v případě, že je synchronizační služba dostupná.
  • Úplný soubor: Soubor byl implicitně hydratován a systém jej může dehydrovat, pokud je potřebný prostor.
  • Připnutý úplný soubor: Uživatel explicitně zajistil dostupnost souboru offline pomocí Průzkumníku souborů.

Následující obrázek ukazuje, jak se v Průzkumníku souborů zobrazují zástupné symboly, úplné a připnuté stavy souborů.

Standardizovaná registrace synchronizačního kořene

• Registrace kořenového adresáře synchronizace je jednoduchá a standardizovaná. To zahrnuje vytvoření uzlu s vlastním označením v navigačním podokně Průzkumníka souborů, jak je znázorněno na následujícím snímku obrazovky. Kořeny lze vytvořit buď jako jednotlivé položky nejvyšší úrovně, nebo jako podřízené položky nadřazeného seskupení.

  

Integrace prostředí

• Ikony stavu:
  • Rozhraní API pro cloudové soubory poskytuje standardizované ikony automatického stavu hydrace zobrazené v Průzkumníku souborů a na ploše Windows.
  • Kromě standardních ikon stavu Windows používaných pro stav hydrace můžete zadat vlastní ikony stavu pro další vlastnosti specifické pro službu.
  • Nahradí starší rozšíření prostředí překrytí ikon.
• Indikátor průběhu:
  • Otevření zástupného souboru, jehož hydratace trvá déle než několik sekund, zobrazí průběh hydratace. Průběh se zobrazuje na několika místech v závislosti na kontextu.
    • V dialogovém okně modulu kopírování.
    • Průběžný průběh se zobrazí vedle souboru v Průzkumníku souborů.
    • Pokud se soubor neotevře v konkrétní instrukci uživatele, zobrazí se informační zpráva, která uživatele informuje a poskytne způsob, jak řídit nezamýšlenou hydrační aktivitu.
• Miniatury a metadata:
  • Zástupné soubory můžou mít bohaté miniatury poskytované službou a rozšířená metadata souborů, které uživateli poskytnou bezproblémové prostředí Průzkumníka souborů.
• Navigační podokno Průzkumníka souborů:
  • Registrace kořenového adresáře synchronizace v rozhraní API pro cloudové soubory způsobí, že se v navigačním podokně Průzkumníka souborů zobrazí kořen synchronizace (s ikonou a vlastním názvem).
• Nabídky kontextového menu Průzkumníka souborů:
  • Registrace kořenového adresáře synchronizace v rozhraní API pro cloudové soubory automaticky poskytuje několik příkazů (položek nabídky) v kontextové nabídce Průzkumníka souborů, které uživateli umožňují řídit stav synchronizace souboru.
  • Do této části místní nabídky lze přidat další slovesa pomocí rozhraní API kompatibilních s Desktop Bridgem.
• Uživatelská kontrola hydrace souborů:
  • Uživatelé mají vždy kontrolu nad hydrací souborů, i když nejsou soubory explicitně hydratovány uživatelem. Interaktivní informační zpráva se zobrazí pro hydrataci na pozadí, která uživatele upozorní a poskytne možnosti. Následující obrázek ukazuje informační oznámení pro hydratační soubor.
  • Pokud uživatel zablokuje aplikaci v hydrataci souborů pomocí interaktivního oznámení, může ji odblokovat na stránce Automatické stahování souborů v Nastavení.
• Operace s připojovacím modulem kopírování (podporované v buildu 19624 a novějších verzích Windows 10 Insider Preview):
  • Poskytovatelé cloudového úložiště můžou zaregistrovat kopírovací háček shellu pro monitorování souborových operací ve synchronizačním kořeni.
  • Poskytovatel zaregistruje svůj háček kopírování nastavením hodnoty registru CopyHook pod klíčem kořenového registru synchronizace na CLSID objektu místního serveru COM. Tento objekt místního serveru implementuje rozhraní IStorageProviderCopyHook .
• Sdílení souborů (podporované ve Windows 11 verze 21H2 a novějších verzích):
  • Poskytovatelé cloudového úložiště mohou zaregistrovat obslužnou rutinu sdílení, která se vyvolá, když uživatel vybere příkaz Sdílet u cloudového souboru v jejich synchronizačním kořeni.
  • Poskytovatel zaregistruje obslužnou rutinu sdílení nastavením hodnoty registru ShareHandler pod svým kořenovým klíčem registru synchronizace na CLSID objektu místního serveru COM. Tento objekt místního serveru implementuje IExplorerCommand rozhraní.

Přemostění na desktop

• Synchronizační moduly využívající rozhraní API cloudových souborů jsou navržené tak, aby jako požadavek na implementaci používaly desktopový most .

Ukázka cloudového zrcadlení

Ukázka cloudového zrcadlení ukazuje, jak vytvořit řešení, které používá rozhraní API pro cloudové soubory. Není určen k použití jako produkčního kódu. Nemá robustní zpracování chyb a je napsané tak, aby bylo co nejsnáže pochopitelné. Nazývá se Cloud Mirror, protože jednoduše zrcadlí místní složku na místním disku. Zadáte složku serveru, která má představovat váš cloudový souborový server, a klientskou složku, která má určit kořenovou cestu synchronizace. Uzel nejvyšší úrovně se zobrazí v navigačním podokně v Průzkumníku souborů s názvem TestStorageProviderDisplayName a tento uzel se mapuje na zadanou složku klienta.

Pokud jde o synchronizaci, jedná se o věci, které musí implementovat plně vyvinutý poskytovatel synchronizace cloudových souborů:

• Pokud je kořen synchronizace pouze zástupný symbol, služba zodpovídá za kopírování obsahu souboru za účelem hydratace. To je implementováno v ukázce.
• Pokud je kořenovým souborem synchronizace úplný soubor a obsah souboru v cloudové službě se změní, zodpovídá služba za upozornění místního synchronizačního klienta na změnu a klient místní synchronizace musí zpracovávat sloučení podle vlastních specifikací. Toto není v ukázce implementováno.
• Pokud je kořenovým souborem synchronizace úplný soubor a obsah souboru v kořenové cestě synchronizace (místní klient) se změní, musí klient místní synchronizace upozornit cloudovou službu a zpracovat sloučení podle vlastních specifikací. Oznámení o změně místního souboru se implementuje v ukázce, ale nic nedělá.

Použijte ukázku

1. Na místním pevném disku vytvořte dvě složky. Jeden z nich bude fungovat jako server a druhý jako klient.
2. Přidejte do složky serveru některé soubory. Ujistěte se, že je složka klienta prázdná.
3. Otevřete ukázku Cloud Mirror v sadě Visual Studio. Nastavte projekt CloudMirrorPackage jako spouštěný projekt a pak sestavte a spusťte ukázku. Když vás aplikace vyzve, zadejte dvě cesty ke složkám serveru a klienta. Po tomto zobrazení se zobrazí okno konzoly s diagnostickými informacemi.
4. Otevřete Průzkumníka souborů a potvrďte, že se zobrazí uzel TestStorageProviderDisplayName a zástupné symboly pro všechny soubory, které jste zkopírovali do složky serveru. Pokud chcete simulovat aplikaci, která se pokusí otevřít soubory bez použití nástroje pro výběr, zkopírujte několik obrázků do složky serveru. Poklikejte na jeden z nich v kořenové složce synchronizace a potvrďte, že hydratuje. Pak otevřete aplikaci Fotky. Aplikace předem načte sousední soubory na pozadí, aby byla pravděpodobnost, že uživatel při prohlížení ostatních obrázků nevyskytují žádná zpoždění. Můžete sledovat, jak dochází k dehydraci pozadí prostřednictvím informačních toastů nebo v Průzkumníku souborů.
5. Klikněte pravým tlačítkem myši na soubor v Průzkumníku souborů, čímž vyvoláte místní nabídku, a potvrďte, že vidíte položku nabídky TestCommand. Po kliknutí na tuto položku nabídky se zobrazí okno se zprávou.
6. Pokud chcete ukázku zastavit, nastavte fokus na výstup konzoly a stiskněte Ctrl-C. Tím se vyčisí registrace kořenového adresáře synchronizace, aby se poskytovatel odinstaloval. Pokud vzorek zhavaruje, je možné, že kořen synchronizace zůstane registrován. To způsobí opětovné spuštění Průzkumníka souborů pokaždé, když kliknete na cokoli a zobrazí se výzva k zadání falešných klientských a serverových umístění. Pokud k tomu dojde, odinstalujte z počítače ukázkovou aplikaci CloudMirrorPackage .

Ukázková architektura

Ukázka je záměrně jednoduchá. Používá statické třídy, aby bylo zbytečné předávat ukazatele instance. Tady jsou hlavní třídy v ukázce:

• FakeCloudProvider: Tato třída nejvyšší úrovně řídí následující třídy pracovních procesů:
  • CloudProviderRegistrar: Zaregistruje synchronizační kořenové informace v prostředí Windows Shell.
  • Zástupné symboly: Vygeneruje soubory zástupných symbolů v kořenové cestě synchronizace.
  • ShellServices: Vytváří služby Windows Shell pro místní nabídku, miniatury a další služby.
  • CloudProviderSyncRootWatcher: Vytvoří instanci DirectoryWatcher, aby monitoroval změny v kořenové cestě synchronizace a reagoval na změny.
  • FileCopierWithProgress: Kopíruje soubory ze složky serveru do klientské složky pomalu v blocích dat, aby bylo simulované jejich stahování ze skutečného cloudového serveru. Poskytuje indikátor průběhu, aby notifikační okna a uživatelské rozhraní Průzkumníka souborů zobrazovaly uživateli informativní obsah.

Kromě výše uvedených tříd ukázka také poskytuje několik pomocných tříd, které uživatele vyzve k zadání složek a některých nástrojů. Všechny příklady zprostředkovatelů služby Shell jsou TestExplorerCommandHandler, CustomStateProvider, ThumbnailProvider a UriSource .

Architektura rozhraní API cloudových souborů

Jádrem zásobníku úložiště v rozhraní API cloudových souborů je ovladač minifiltru systému souborů, který se nazývá cldflt.sys. Tento ovladač funguje jako proxy mezi aplikacemi uživatele a synchronizačním modulem. Synchronizační modul ví, jak stahovat a nahrávat data na vyžádání, zatímco je zodpovědností cldflt.sys pracovat se službou Shell a prezentovat soubory, jako by byla cloudová data místně dostupná.

Cldflt.sys aktuálně podporuje jenom svazky NTFS, protože závisí na některých funkcích, které jsou pro ntfs jedinečné.

V systému je mnoho ovladačů minifiltru systému souborů a mohou být aktivní na daném svazku současně. Ovladače, které jsou nejvíce zajímavé pro rozhraní API pro cloudové soubory, jsou antivirové filtry systému souborů.

Ovladače minifiltru systému souborů se spravují a podporují speciální komponentou režimu jádra, která se nazývá správce filtrů. Kromě mnoha dalších povinností usnadňuje správce filtru nefiltrovanou komunikaci mezi filtry a komponentami uživatelského režimu prostřednictvím konstruktoru označovaného jako port zprávy filtru.

Zásady hydrace

Systém Windows podporuje řadu primárních zásad hydrace a modifikátorů sekundární hydrace. Zásady primární hydrace mají toto pořadí:

Úplná úplná >> progresivní částečná >

Aplikace i synchronizační moduly mohou definovat své upřednostňované zásady primární hydrace. Pokud není stanoveno jinak, výchozí pravidla hydrace jsou pro aplikace i synchronizační moduly postupná.

Zásady hydrace cloudového souboru se určují v době otevření souboru tímto vzorcem:

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

Řekněme například, že se uživatel pokouší otevřít soubor PDF uložený na cloudové jednotce Fabrikam pomocí Prohlížeče PDF společnosti Contoso, který nezadá upřednostňovanou zásadu hydrace. Zásada zavlažování aplikace je proto postupné zavlažování, v tomto případě výchozí. Vzhledem k tomu, že Fabrikam Cloud Drive je synchronizační modul s plnou hydratací, konečnou zásadou hydrace souboru je plná hydratace, což způsobí, že se soubor plně hydratuje při prvním přístupu. Stejný výsledek se projeví v případech, kdy synchronizační modul podporuje postupnou hydraci, ale preference aplikace je plná hydrace.

Všimněte si, že zásady hydrace souboru nelze po otevření souboru změnit.

Kompatibilita s aplikacemi, které používají spojovací body

Rozhraní API pro cloudové soubory implementuje zástupný systém pomocí spojovacích bodů. Běžným omylem o spojovacích bodech je, že jsou stejné jako symbolické odkazy. Tato počáteční chybná představa se občas odráží v implementacích aplikací, a v důsledku toho mnoho běžících aplikací narazí na chyby při setkání s jakýmkoli přesměrovacím bodem.

Aby se tento problém s kompatibilitou zmírnilo, rozhraní API cloudových souborů vždy skryje přepojovací body ze všech aplikací s výjimkou synchronizačních modulů a procesů, jejichž hlavní obraz se nachází v %systemroot%. Aplikace, které správně rozumí reparse bodům, mohou vynutit, aby platforma zpřístupnila reparse body API pro cloudové soubory pomocí RtlSetProcessPlaceholderCompatibilityMode nebo RtlSetThreadProcessPlaceholderCompatibilityMode.

Hledání cloudových souborů

Vyhledávání cloudových souborů se podporuje ve Windows 11 verze 24H2 a novějších na počítačích Copilot+ nebo cloudových počítačích s podporou AI. Pro poskytovatele cloudového úložiště jsou k dispozici následující funkce pro integraci se službou Windows Search:

• Poskytovatelé cloudového úložiště můžou zaregistrovat obslužnou rutinu vyhledávání souborů pro svůj kořen synchronizace a umožnit jim přispívat výsledky hledání do Průzkumníka souborů a služby Windows Search.
• Poskytovatelé cloudového úložiště zaregistrují obslužnou rutinu vyhledávání nastavením hodnoty registru SearchHandlerFactory v rámci klíče kořenového registru synchronizace na CLSID objektu místního serveru COM. Tento objekt místního serveru implementuje rozhraní IStorageProviderSearchHandlerFactory .
• IStorageProviderSearchHandlerFactory vytvoří implementaci IStorageProviderSearchHandler. Tato implementace IStorageProviderSearchHandler volá vyhledávací službu poskytovatele cloudu k vyhledávání souborů, které nemusí být dostupné místně na zařízení.
• Prostředí Windows Search volá metodu Find během hledání a slučuje výsledky s výsledky z místního indexeru vyhledávání.

Související obsah

Integrace poskytovatele cloudových souborů se službou Windows Search

IStorageProviderSearchHandlerFactory

Obor názvů Windows.Storage.Provider