Śledzenie zmian w systemie plików w tle

ważne interfejsy API

Klasa StorageLibraryChangeTracker umożliwia aplikacjom śledzenie zmian w plikach i folderach podczas poruszania się po systemie przez użytkowników. Te interfejsy API WinRT mogą być używane w aplikacjach WinUI 3 utworzonych za pomocą Zestaw SDK do aplikacji systemu Windows, które obsługują Windows 10 w wersji 1809 (kompilacja 17763) lub nowszej. Podstawowy interfejs API StorageLibraryChangeTracker jest dostępny od wersji Windows 10 w wersji 1803 (kompilacja 17134). Korzystając z klasy StorageLibraryChangeTracker, aplikacja może śledzić:

  • Operacje na plikach, w tym dodawanie, usuwanie, modyfikowanie.
  • Operacje folderów, takie jak zmienianie nazw i usuwanie.
  • Pliki i foldery przenoszone na dysku.

Skorzystaj z tego przewodnika, aby poznać model programowania do pracy z monitorem zmian, wyświetlić przykładowy kod i zrozumieć różne typy operacji na plikach śledzonych przez usługę StorageLibraryChangeTracker.

Funkcja StorageLibraryChangeTracker działa w przypadku bibliotek użytkowników lub dowolnego folderu na komputerze lokalnym. Dotyczy to dysków pomocniczych lub dysków wymiennych, ale nie obejmuje dysków NAS ani dysków sieciowych.

Wymagania wstępne

  • aplikacja WinUI 3 przeznaczona dla Windows 10, wersja 1809 lub nowsza — Zestaw SDK do aplikacji systemu Windows / WinUI 3 jest obsługiwana od wersji Windows 10 w wersji 1809 (kompilacja 17763). Podstawowy interfejs API StorageLibraryChangeTracker wymaga Windows 10 w wersji 1803 (kompilacja 17134). Jeśli tworzysz nowy projekt, ustaw odpowiednio minimalną wersję w pliku .csproj.

  • Wymagane using dyrektywy

    using Windows.Storage;

  • Deklaracje możliwości — aplikacja musi zadeklarować odpowiednie możliwości biblioteki w programie Package.appxmanifest przed uzyskaniem dostępu do elementu StorageLibrary. Aby uzyskać szczegółowe informacje, zobacz Uprawnienia dostępu do plików .

Korzystanie z monitora zmian

Monitor zmian jest implementowany w systemie jako bufor cykliczny przechowując ostatnie N operacji systemu plików. Aplikacje mogą odczytywać zmiany z buforu, a następnie przetwarzać je do własnych doświadczeń. Gdy aplikacja zakończy pracę ze zmianami, oznacza je jako przetworzone i nigdy nie przetworzy ich ponownie.

Aby użyć monitora zmian w folderze, wykonaj następujące kroki:

  1. Włącz śledzenie zmian dla folderu.
  2. Poczekaj na zmiany.
  3. Przeczytaj zmiany.
  4. Zaakceptuj zmiany.

W następnych sekcjach opisano poszczególne kroki z przykładami kodu. Kompletny przykład kodu znajduje się na końcu artykułu.

Włączanie monitora zmian

Pierwszą rzeczą, którą aplikacja musi zrobić, jest powiedzenie systemowi, że interesuje go śledzenie zmian w danej bibliotece. W tym celu wywołaj metodę Enable w śledzeniu zmian dla interesującej biblioteki.

StorageLibrary videosLib = await StorageLibrary.GetLibraryAsync(KnownLibraryId.Videos);
StorageLibraryChangeTracker videoTracker = videosLib.ChangeTracker;
videoTracker.Enable();

Kilka ważnych uwag:

  • Przed utworzeniem obiektu Package.appxmanifest upewnij się, że aplikacja zadeklarowała odpowiednią funkcję biblioteki. Aby uzyskać więcej informacji, zobacz Uprawnienia dostępu do plików .
  • Włącz jest bezpieczne dla wątków, nie zresetuje wskaźnika i może być wywoływany dowolną liczbę razy (więcej na ten temat później).

Włączanie pustego monitora zmian

Czekaj na zmiany

Po zainicjowaniu monitora zmian rozpocznie się rejestrowanie wszystkich operacji wykonywanych w bibliotece, nawet jeśli aplikacja nie jest uruchomiona. Aplikacje mogą się rejestrować do aktywacji przy każdej zmianie, korzystając ze zdarzenia StorageLibraryChangedTrigger.

Zmiany dodawane do monitora zmian bez odczytywania ich przez aplikację

Przeczytaj zmiany

Aplikacja może następnie sprawdzać zmiany z monitora zmian i otrzymywać listę tych zmian od czasu ostatniego sprawdzenia. Poniższy kod pokazuje, jak uzyskać listę zmian z monitora zmian.

StorageLibrary videosLibrary = await StorageLibrary.GetLibraryAsync(KnownLibraryId.Videos);
videosLibrary.ChangeTracker.Enable();
StorageLibraryChangeReader videoChangeReader = videosLibrary.ChangeTracker.GetChangeReader();
IReadOnlyList<StorageLibraryChange> changeSet = await videoChangeReader.ReadBatchAsync();

Aplikacja jest następnie odpowiedzialna za przetwarzanie zmian we własnym środowisku lub bazie danych zgodnie z potrzebami.

Odczytywanie zmian z monitora zmian w bazie danych aplikacji

Wskazówka

Drugie wywołanie włączenia polega na obronie przed warunkiem wyścigu, jeśli użytkownik doda inny folder do biblioteki podczas odczytywania zmian w aplikacji. Bez dodatkowego wywołania funkcji Enable, kod zakończy się niepowodzeniem z błędem ecSearchFolderScopeViolation (0x80070490), jeśli użytkownik zmienia foldery w swojej bibliotece.

Zaakceptuj zmiany

Po zakończeniu przetwarzania zmian aplikacja powinna poinformować system, aby nigdy nie pokazywał tych zmian ponownie, wywołując metodę AcceptChangesAsync .

await videoChangeReader.AcceptChangesAsync();

Oznaczanie zmian jako przeczytanych, aby nigdy nie były wyświetlane ponownie

Aplikacja będzie teraz otrzymywać nowe zmiany tylko wtedy, gdy w przyszłości będzie odczytywany rejestr zmian.

  • Jeśli zmiany wystąpiły między wywołaniem funkcji ReadBatchAsync i AcceptChangesAsync, wskaźnik zostanie zaawansowany tylko do najnowszej zmiany, która została zaobserwowana przez aplikację. Te inne zmiany będą nadal dostępne przy następnym wywołaniu funkcji ReadBatchAsync.
  • Nieakceptowanie zmian spowoduje, że system zwróci ten sam zestaw zmian przy następnym wywołaniu aplikacji ReadBatchAsync.

Ważne kwestie do zapamiętania

W przypadku korzystania z trackera zmian należy pamiętać o kilku kwestiach, aby upewnić się, że wszystko działa prawidłowo.

Przepełnienia bufora

Mimo że staramy się zarezerwować wystarczającą ilość miejsca w rejestrze zmian, aby przechowywać wszystkie operacje wykonywane w systemie do chwili gdy aplikacja je odczyta, bardzo łatwo sobie wyobrazić scenariusz, w którym aplikacja nie odczytuje zmian, zanim bufor cykliczny się nadpisze. Zwłaszcza jeśli użytkownik przywraca dane z kopii zapasowej lub synchronizuje dużą kolekcję zdjęć z telefonu z aparatem.

W takim przypadku narzędzie ReadBatchAsync zwróci kod błędu StorageLibraryChangeType.ChangeTrackingLost. Jeśli aplikacja otrzymuje ten kod błędu, oznacza to kilka rzeczy:

  • Bufor nadpisał się od czasu ostatniego przyjrzenia się temu. Najlepszym sposobem działania jest ponowne przeszukiwanie biblioteki, ponieważ wszelkie informacje z procesu śledzenia będą niekompletne.
  • Monitor zmian nie zwróci żadnych kolejnych zmian do momentu wywołania funkcji Resetuj. Po tym jak aplikacja wywoła reset, wskaźnik zostanie przeniesiony do najnowszej zmiany, a śledzenie zostanie wznowione w zwykły sposób.

Przypadki te powinny być rzadkie, ale w scenariuszach, w których użytkownik przenosi dużą liczbę plików na dysku, nie chcemy, aby monitor zmian nadmiernie się rozrósł i zajmował zbyt dużo miejsca. Powinno to pozwolić aplikacjom reagować na ogromne operacje systemu plików, nie uszkadzając środowiska klienta w systemie Windows.

Zmiany w bibliotece przechowywania

Klasa StorageLibrary istnieje jako wirtualna grupa folderów głównych, które zawierają inne foldery. Aby uzgodnić to z monitorem zmian systemu plików, dokonaliśmy następujących wyborów:

  • Wszelkie zmiany w potomkach folderu głównego biblioteki będą reprezentowane w rejestrze zmian. Foldery biblioteki głównej można znaleźć przy użyciu właściwości Foldery .
  • Dodawanie lub usuwanie folderów głównych z biblioteki StorageLibrary (za pośrednictwem elementu RequestAddFolderAsync i RequestRemoveFolderAsync) nie spowoduje utworzenia wpisu w monitorze zmian. Te zmiany można śledzić za pomocą zdarzenia DefinitionChanged lub wyliczając foldery główne w bibliotece przy użyciu właściwości Foldery .
  • Jeśli folder z już istniejącą zawartością zostanie dodany do biblioteki, nie wygeneruje się powiadomienie o zmianie ani wpisy śledzenia zmian. Wszelkie kolejne zmiany podrzędnych elementów tego folderu będą generować powiadomienia i wpisy w rejestrze zmian.

Wywoływanie metody Enable

Aplikacje powinny wywoływać funkcję Włącz zaraz po rozpoczęciu śledzenia systemu plików i przed każdym wyliczeniem zmian. Dzięki temu wszystkie zmiany zostaną przechwycone przez monitor zmian.

Składanie całości

Oto cały kod używany do rejestrowania zmian w bibliotece wideo i rozpoczynanie ściągania zmian z monitora zmian.

private async void EnableChangeTracker()
{
    StorageLibrary videosLib = await StorageLibrary.GetLibraryAsync(KnownLibraryId.Videos);
    StorageLibraryChangeTracker videoTracker = videosLib.ChangeTracker;
    videoTracker.Enable();
}

private async void GetChanges()
{
    StorageLibrary videosLibrary = await StorageLibrary.GetLibraryAsync(KnownLibraryId.Videos);
    videosLibrary.ChangeTracker.Enable();
    StorageLibraryChangeReader videoChangeReader = videosLibrary.ChangeTracker.GetChangeReader();
    IReadOnlyList<StorageLibraryChange> changeSet = await videoChangeReader.ReadBatchAsync();

    foreach (StorageLibraryChange change in changeSet)
    {
        if (change.ChangeType == StorageLibraryChangeType.ChangeTrackingLost)
        {
            // The circular buffer overflowed. Recrawl the library from scratch.
            videosLibrary.ChangeTracker.Reset();
            return;
        }
        if (change.IsOfType(StorageItemTypes.File))
        {
            await HandleFileChange(change);
        }
        else if (change.IsOfType(StorageItemTypes.Folder))
        {
            await HandleFolderChange(change);
        }
        else if (change.IsOfType(StorageItemTypes.None))
        {
            if (change.ChangeType == StorageLibraryChangeType.Deleted)
            {
                RemoveItemFromDB(change.Path);
            }
        }
    }
    await videoChangeReader.AcceptChangesAsync();
}
  • Last updated on