Monitorar alterações no sistema de arquivos em segundo plano

APIs importantes

• StorageLibraryChangeTracker
• StorageLibraryChangeReader
• StorageLibraryChangedTrigger
• BibliotecaDeArmazenamento

A classe StorageLibraryChangeTracker permite que os aplicativos rastreiem alterações em arquivos e pastas à medida que os usuários os movem pelo sistema. Usando a classe StorageLibraryChangeTracker , um aplicativo pode rastrear:

• Operações de arquivo, incluindo adicionar, excluir, modificar.
• Operações de pasta, como renomear e excluir.
• Arquivos e pastas em movimento na unidade.

Use este guia para aprender o modelo de programação para trabalhar com o controlador de alterações, exibir alguns exemplos de código e entender os diferentes tipos de operações de arquivo que são rastreadas pelo StorageLibraryChangeTracker.

StorageLibraryChangeTracker funciona para bibliotecas de usuários ou para qualquer pasta na máquina local. Isso inclui unidades secundárias ou unidades removíveis, mas não inclui unidades NAS ou unidades de rede.

Usando o controle de alterações

O controlador de alterações é implementado no sistema como um buffer circular que armazena as últimas operações do sistema de arquivos N . Os aplicativos são capazes de ler as alterações do buffer e, em seguida, processá-las em suas próprias experiências. Quando o aplicativo termina com as alterações, ele marca as alterações como processadas e nunca mais as verá.

Para usar o controle de alterações em uma pasta, siga estas etapas:

1. Habilite o controle de alterações para a pasta.
2. Aguarde alterações.
3. Leia as alterações.
4. Aceitar alterações.

As próximas seções percorrem cada uma das etapas com alguns exemplos de código. O exemplo de código completo é fornecido no final do artigo.

Ativar o rastreador de alterações

A primeira coisa que o aplicativo precisa fazer é dizer ao sistema que ele está interessado no controle de alterações de uma determinada biblioteca. Isto é feito chamando o método Enable no rastreador de alterações para a biblioteca de interesse.

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

Algumas observações importantes:

• Verifique se seu aplicativo tem permissão para a biblioteca correta no manifesto antes de criar o objeto StorageLibrary . Consulte de permissões de acesso a arquivos para obter mais detalhes.
• Ativar é seguro para threads, não redefinirá o seu ponteiro e pode ser chamado quantas vezes desejar (abordaremos isso mais à frente).

Aguarde alterações

Depois que o controlador de alterações for inicializado, ele começará a registrar todas as operações que ocorrem em uma biblioteca, mesmo enquanto o aplicativo não estiver em execução. As aplicações podem inscrever-se para serem ativadas sempre que houver uma alteração, registando-se para o evento StorageLibraryChangedTrigger.

Leia as alterações

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

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

O aplicativo é então responsável por processar as alterações em sua própria experiência ou banco de dados, conforme necessário.

Aceitar as alterações

Após o aplicativo terminar de processar as alterações, deve dizer ao sistema para nunca mais mostrar essas alterações, chamando o método AcceptChangesAsync.

await changeReader.AcceptChangesAsync();

O aplicativo agora só receberá novas alterações ao ler o rastreador de alterações no futuro.

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

Coisas importantes para lembrar

Ao usar o rastreador de alterações, há algumas coisas que você deve ter em mente para se certificar de que tudo está funcionando corretamente.

Estouros de buffer

Embora tentemos reservar espaço suficiente no controlador de alterações para manter todas as operações que acontecem no sistema até que seu aplicativo possa lê-las, é muito fácil imaginar um cenário em que o aplicativo não lê as alterações antes que o buffer circular se sobrestitua. Especialmente se o usuário estiver restaurando dados de um backup ou sincronizando uma grande coleção de imagens de seu telefone com câmera.

Nesse caso, ReadBatchAsync retornará o código de erro StorageLibraryChangeType.ChangeTrackingLost. Se o seu aplicativo receber esse código de erro, isso significa algumas coisas:

• O buffer substituiu-se desde a última vez que você olhou para ele. O melhor curso de ação é rastrear novamente a biblioteca, porque todas as informações do rastreador estarão incompletas.
• O rastreador de alterações não retornará mais alterações até que você chame Reiniciar. Após o aplicativo chamar a função de redefinição, o ponteiro será movido para a alteração mais recente e o rastreamento será retomado normalmente.

Deve ser raro obter esses casos, mas em cenários em que o usuário está movendo um grande número de arquivos em seu disco, não queremos que o rastreador de alterações aumente e ocupe muito armazenamento. Isso deve permitir que os aplicativos reajam a operações massivas do sistema de arquivos, sem prejudicar a experiência do cliente no Windows.

Alterações em uma StorageLibrary

A classe StorageLibrary existe como um grupo virtual de pastas raiz que contêm outras pastas. Para reconciliar isso com um rastreador de alterações do sistema de arquivos, fizemos as seguintes escolhas:

• Quaisquer alterações nos descendentes das pastas da biblioteca raiz serão representadas nos rastreadores de alterações. As pastas da biblioteca raiz podem ser encontradas usando a propriedade Folders .
• Adicionar ou remover pastas raiz de uma StorageLibrary (através de RequestAddFolderAsync e RequestRemoveFolderAsync) não criará uma entrada no rastreador de alterações. Essas alterações podem ser controladas por meio do evento DefinitionChanged ou enumerando as pastas raiz na biblioteca usando a propriedade Folders .
• Se uma pasta com conteúdo já nela for adicionada à biblioteca, não haverá uma notificação de alteração ou entradas do controlador de alterações geradas. Quaisquer alterações subsequentes nos descendentes dessa pasta gerarão notificações e alterarão as entradas do rastreador.

Chamando o método Enable

As aplicações devem chamar Ativar assim que iniciarem a monitorizar o sistema de arquivos e antes da enumeração de cada uma das alterações. Isso garantirá que todas as alterações serão capturadas pelo rastreador de alterações.

Juntando tudo

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

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