Suivre les modifications apportées au système de fichiers en arrière-plan

Les APIs importantes

• SuiviDesChangementsDeBibliothèqueDeStockage
• StorageLibraryChangeReader
• DéclencheurDeChangementDeBibliothèqueDeStockage
• Bibliothèque de stockage

La classe StorageLibraryChangeTracker permet aux applications de suivre les modifications apportées aux fichiers et dossiers lorsque les utilisateurs les déplacent dans le système. À l’aide de la classe StorageLibraryChangeTracker, une application peut suivre :

• Opérations de fichier, notamment ajouter, supprimer, modifier.
• Opérations de dossier telles que les renommages et les suppressions.
• Les fichiers et dossiers sont déplacés sur le disque.

Utilisez ce guide pour apprendre le modèle de programmation pour utiliser le suivi des modifications, afficher un exemple de code et comprendre les différents types d’opérations de fichier suivies par StorageLibraryChangeTracker.

StorageLibraryChangeTracker fonctionne pour les bibliothèques utilisateur ou pour n’importe quel dossier sur l’ordinateur local. Cela inclut les lecteurs secondaires ou les lecteurs amovibles, mais n’inclut pas les lecteurs NAS ou les lecteurs réseau.

Utilisation du suivi des modifications

Le suivi des modifications est implémenté sur le système en tant que mémoire tampon circulaire stockant les dernières opérations du système de fichiers N. Les applications peuvent lire les modifications de la mémoire tampon, puis les traiter dans leurs propres expériences. Une fois que l’application a terminé d’apporter les modifications, elle les marque comme traitées et ne les verra plus jamais.

Pour utiliser le suivi des modifications sur un dossier, procédez comme suit :

1. Activez le suivi des modifications pour le dossier.
2. Attendez les modifications.
3. Lire les modifications.
4. Accepter les modifications.

Les sections suivantes décrivent chacune des étapes avec quelques exemples de code. L’exemple de code complet est fourni à la fin de l’article.

Activer le suivi des modifications

La première chose que l’application doit faire est de dire au système qu’elle s’intéresse au suivi des modifications d’une bibliothèque donnée. Pour ce faire, en effectuant un appel à la méthode Enable sur le traceur de modifications de la bibliothèque d'intérêt.

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

Quelques remarques importantes :

• Vérifiez que votre application dispose de l’autorisation pour la bibliothèque correcte dans le manifeste avant de créer l’objet StorageLibrary. Pour plus d’informations, consultez autorisations d’accès aux fichiers.
• Activer est sécurisé pour les threads, ne réinitialise pas votre pointeur et peut être appelé autant de fois que vous le souhaitez (plus sur ce point plus tard).

Attendre les modifications

Une fois le suivi des modifications initialisé, il commence à enregistrer toutes les opérations qui se produisent dans une bibliothèque, même si l’application n’est pas en cours d’exécution. Les applications peuvent s’inscrire pour être activées chaque fois qu’il existe une modification en vous inscrivant pour l’événement StorageLibraryChangedTrigger.

Lire les modifications

L'application peut ensuite interroger le système de suivi des modifications et recevoir une liste des modifications depuis la dernière consultation. Le code ci-dessous montre comment obtenir une liste des modifications à partir du traqueur de modifications.

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

L’application est ensuite chargée de traiter les modifications dans sa propre expérience ou sa propre base de données en fonction des besoins.

Accepter les modifications

Une fois que l’application a terminé le traitement des modifications, il doit indiquer au système de ne jamais afficher ces modifications à nouveau en appelant la méthode AcceptChangesAsync.

await changeReader.AcceptChangesAsync();

L’application ne recevra désormais que de nouvelles modifications lors de la lecture du suivi des modifications à l’avenir.

• Si des modifications se sont produites entre l'appel de ReadBatchAsync et le AcceptChangesAsync, le pointeur ne sera avancé que jusqu’à la dernière modification que l'application a enregistrée. Ces autres modifications seront toujours disponibles la prochaine fois qu’elle appelle ReadBatchAsync.
• Si vous n’acceptez pas les modifications, le système retourne le même jeu de modifications la prochaine fois que l’application appelle ReadBatchAsync.

Éléments importants à mémoriser

Lorsque vous utilisez le suivi des modifications, il existe quelques éléments que vous devez garder à l’esprit pour vous assurer que tout fonctionne correctement.

Dépassements de mémoire tampon

Même si nous essayons de réserver suffisamment d’espace dans le suivi des modifications pour contenir toutes les opérations qui se produisent sur le système jusqu’à ce que votre application puisse les lire, il est très facile d’imaginer un scénario où l’application ne lit pas les modifications avant que la mémoire tampon circulaire ne se remplace. En particulier si l’utilisateur restaure des données à partir d’une sauvegarde ou synchronise une grande collection d’images à partir de son téléphone photo.

Dans ce cas, ReadBatchAsync retourne le code d’erreur StorageLibraryChangeType.ChangeTrackingLost. Si votre application reçoit ce code d’erreur, cela signifie quelques éléments :

• La mémoire tampon s'est réécrite depuis la dernière fois que vous l'avez regardée. La meilleure approche consiste à explorer de nouveau la bibliothèque, car toute information provenant du traceur sera incomplète.
• Le suivi des modifications ne renverra plus de modifications tant que vous n’appelez Réinitialiser. Une fois les appels d’application réinitialisés, le pointeur est déplacé vers la modification la plus récente et le suivi reprend normalement.

Il devrait être rare de rencontrer ce genre de situation, mais dans les cas où l'utilisateur déplace un grand nombre de fichiers sur son disque, nous ne voulons pas que le dispositif de suivi des modifications s'enfle et prenne trop d'espace de stockage. Cela doit permettre aux applications de réagir aux opérations massives du système de fichiers tout en n’endommageant pas l’expérience client dans Windows.

Modifications apportées à un StorageLibrary

La classe StorageLibrary existe en tant que groupe virtuel de dossiers racines qui contiennent d’autres dossiers. Pour rapprocher cela d’un suivi des modifications du système de fichiers, nous avons fait les choix suivants :

• Toutes les modifications apportées à la descendance des dossiers de bibliothèque racine sont représentées dans le suivi des modifications. Vous trouverez les dossiers de la bibliothèque racine à l’aide de la propriété Folders.
• L’ajout ou la suppression de dossiers racines d’un StorageLibrary (via RequestAddFolderAsync et RequestRemoveFolderAsync) ne crée pas d’entrée dans le suivi des modifications. Ces modifications peuvent être suivies via l’événement DefinitionChanged ou en énumérant les dossiers racines de la bibliothèque à l’aide de la propriété Folders .
• Si un dossier contenant déjà du contenu est ajouté à la bibliothèque, il n’y aura pas de notification de modification ni d’entrées de suivi des modifications générées. Toutes les modifications suivantes apportées aux descendants de ce dossier génèrent des notifications et des entrées de suivi des modifications.

Appel de la méthode Enable

Les applications doivent appeler Activer dès qu’elles commencent à suivre le système de fichiers et avant chaque énumération des modifications. Cela garantit que toutes les modifications seront capturées par le suivi des modifications.

Mettez-le ensemble

Voici tout le code utilisé pour s'abonner aux modifications de la vidéothèque et commencer à récupérer les modifications du suivi des changements.

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 changeSet = await changeReader.ReadBatchAsync();


    //Below this line is for the blog post. Above the line is for the magazine
    foreach (StorageLibraryChange change in changeSet)
    {
        if (change.ChangeType == StorageLibraryChangeType.ChangeTrackingLost)
        {
            //We are in trouble. Nothing else is going to be valid.
            log("Resetting the change tracker");
            videosLibrary.ChangeTracker.Reset();
            return;
        }
        if (change.IsOfType(StorageItemTypes.Folder))
        {
            await HandleFileChange(change);
        }
        else if (change.IsOfType(StorageItemTypes.File))
        {
            await HandleFolderChange(change);
        }
        else if (change.IsOfType(StorageItemTypes.None))
        {
            if (change.ChangeType == StorageLibraryChangeType.Deleted)
            {
                RemoveItemFromDB(change.Path);
            }
        }
    }
    await changeReader.AcceptChangesAsync();
}