Monitorizar alterações no sistema de ficheiros em segundo plano

APIs importantes

• RastreadorDeAlteraçõesDeBibliotecaDeArmazenamento
• LeitorDeAlteraçõesDaBibliotecaDeArmazenamento
• ArmazenamentoBibliotecaMudadoTrigger
• StorageLibrary

A classe StorageLibraryChangeTracker permite que as aplicações acompanhem alterações em ficheiros e pastas à medida que os utilizadores os movem pelo sistema. Estas APIs WinRT podem ser usadas a partir de aplicações WinUI 3 construídas com o SDK de Aplicações Windows direcionado para Windows 10, versão 1809 (build 17763) ou posterior. A API subjacente StorageLibraryChangeTracker está disponível a partir de Windows 10, versão 1803 (build 17134). Usando a classe StorageLibraryChangeTracker, uma aplicação pode acompanhar:

• Operações de ficheiros incluindo adicionar, eliminar, modificar.
• Operações de pasta, como renomear e apagar.
• Ficheiros e pastas a moverem-se no disco.

Use este guia para aprender o modelo de programação para trabalhar com o rastreador de alterações, visualizar algum código de exemplo e compreender os diferentes tipos de operações de ficheiros que são monitorizadas pelo StorageLibraryChangeTracker.

O StorageLibraryChangeTracker funciona para bibliotecas de utilizador, ou para qualquer pasta na máquina local. Isto inclui discos secundários ou removíveis, mas não inclui discos NAS ou discos de rede.

Pré-requisitos

• Aplicações WinUI 3 direcionadas para o Windows 10, versão 1809 ou posterior — O SDK de Aplicações do Windows / WinUI 3 é suportado a partir do Windows 10, versão 1809 (build 17763). A API subjacente StorageLibraryChangeTracker requer Windows 10, versão 1803 (build 17134). Se estiver a criar um novo projeto, defina a versão mínima no seu .csproj ficheiro em conformidade.

• Diretivas obrigatórias using

  using Windows.Storage;
  

• Declarações de capacidade — A sua aplicação deve declarar as capacidades apropriadas da biblioteca no seu Package.appxmanifest antes de aceder a um StorageLibrary. Consulte permissões de acesso a ficheiros para mais detalhes.

Utilização do rastreador de alterações

O rastreador de alterações é implementado no sistema como um buffer circular que armazena as últimas N operações do sistema de ficheiros. As aplicações conseguem ler as alterações do buffer e depois processá-las nas suas próprias experiências. Quando a aplicação termina as alterações, marca as alterações como processadas e nunca mais as verá novamente.

Para usar o rastreador de alterações numa pasta, siga estes passos:

1. Ativa o rastreamento de alterações na pasta.
2. Espera por mudanças.
3. Leia as mudanças.
4. Aceita mudanças.

As secções seguintes explicam cada um dos passos com alguns exemplos de código. O exemplo completo de código é fornecido no final do artigo.

Ativar o rastreador de alterações

A primeira coisa que a aplicação precisa de fazer é informar o sistema que está interessada em acompanhar alterações numa determinada biblioteca. Faz isto chamando o método Enable no rastreador de alterações da biblioteca de interesse.

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

Algumas notas importantes:

• Certifique-se de que a sua aplicação declarou a capacidade Package.appxmanifest adequada da biblioteca antes de criar o objeto StorageLibrary . Consulte permissões de acesso a ficheiros para mais detalhes.
• Ativar é seguro para threads, não reinicia o ponteiro e pode ser chamado quantas vezes quiser (falarei mais sobre isto mais adiante).

Aguarde por mudanças

Depois de o rastreador de alterações ser inicializado, começará a registar todas as operações que ocorrem numa biblioteca, mesmo quando a aplicação não estiver a correr. As aplicações podem registar-se para serem ativadas sempre que houver uma alteração, registando-se no evento StorageLibraryChangedTrigger .

Leia as alterações

A aplicação pode então consultar alterações no rastreador de alterações e receber uma lista das alterações desde a última vez que verificou. O código abaixo mostra como obter uma lista de alterações a partir do rastreador de mudanças.

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

A aplicação é então responsável por processar as alterações na sua própria experiência ou base de dados, conforme necessário.

Dica

A segunda opção para ativar é defender contra uma condição de raça se o utilizador adicionar outra pasta à biblioteca enquanto a sua aplicação lê alterações. Sem a chamada extra para Ativar, o código falhará com ecSearchFolderScopeViolation (0x80070490) se o utilizador estiver a alterar as pastas na sua biblioteca

Aceitar as mudanças

Depois de a aplicação terminar de processar as alterações, deverá avisar o sistema para nunca mais mostrar essas alterações, chamando o método AcceptChangesAsync .

await videoChangeReader.AcceptChangesAsync();

A aplicação agora só receberá novas alterações ao ler o rastreador de alterações no futuro.

• Se houver alterações entre chamar o ReadBatchAsync e o AcceptChangesAsync, o ponteiro só será avançado para a alteração mais recente que a aplicação viu. Essas outras alterações permanecerão disponíveis na próxima vez que chamar o ReadBatchAsync.
• Não aceitar as alterações fará com que o sistema devolva o mesmo conjunto de alterações na próxima vez que a aplicação chamar o ReadBatchAsync.

Coisas importantes para lembrar

Ao usar o rastreador de mudanças, há algumas coisas que deve ter em conta para garantir que tudo está a funcionar corretamente.

Estouro de buffer

Embora tentemos reservar espaço suficiente no rastreador de alterações para armazenar todas as operações que acontecem no sistema até que a tua aplicação as consiga ler, é muito fácil imaginar um cenário em que a aplicação não lê as alterações antes do buffer circular se sobreescrever. Especialmente se o utilizador estiver a restaurar dados a partir de um backup ou a sincronizar uma grande coleção de imagens do telemóvel com câmara.

Neste caso, o ReadBatchAsync devolverá o código de erro StorageLibraryChangeType.ChangeTrackingLost. Se a sua aplicação receber este código de erro, isso significa algumas coisas:

• O buffer sobrescreveu-se desde a última vez que o viste. O melhor a fazer é efetuar novamente o rastreio da biblioteca, porque qualquer informação do rastreador ficará incompleta.
• O rastreador de alterações não devolverá mais alterações até chamares o Reset. Depois de a aplicação chamar a função de reiniciar, o ponteiro será movido para a alteração mais recente e o rastreamento retomará normalmente.

Deveria ser raro ter estes casos, mas em cenários em que o utilizador está a mover um grande número de ficheiros no seu disco, não queremos que o rastreador de alterações aumente e ocupe demasiado espaço de armazenamento. Isto deve permitir que as aplicações reajam a operações massivas do sistema de ficheiros sem prejudicar a experiência do cliente no Windows.

Alterações a uma Biblioteca de Armazenamento

A classe StorageLibrary existe como um grupo virtual de pastas raiz que contêm outras pastas. Para conciliar isto com um rastreador de alterações no sistema de ficheiros, fizemos as seguintes escolhas:

• Quaisquer alterações às pastas descendentes da biblioteca raiz serão representadas no rastreador de mudanças. As pastas da biblioteca raiz podem ser encontradas usando a propriedade Pastas .
• Adicionar ou remover pastas raiz de uma StorageLibrary (através de RequestAddFolderAsync e RequestRemoveFolderAsync) não criará uma entrada no rastreador de alterações. Estas alterações podem ser acompanhadas através do evento DefinitionChanged ou enumerando as pastas raiz na biblioteca usando a propriedade Pastas .
• Se uma pasta com conteúdo já incluído for adicionada à biblioteca, não será gerada uma notificação de alteração nem entradas do rastreador de alterações. Quaisquer alterações subsequentes aos descendentes dessa pasta gerarão notificações e alterarão entradas do rastreador.

Chamar o método Enable

As aplicações devem chamar Enable assim que começarem a vigiar o sistema de ficheiros e antes de cada enumeração das alterações. Isto garantirá que todas as alterações serão captadas pelo rastreador de alterações.

Juntando tudo

Aqui está todo o código usado para registar as alterações da biblioteca de vídeo e começar a extrair as alterações do rastreador de mudanças.

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();
}