Criar um mecanismo de sincronização de nuvem que dê suporte a arquivos de espaço reservado

Um mecanismo de sincronização é um serviço que sincroniza arquivos, normalmente entre um host remoto e um cliente local. Os mecanismos de sincronização no Windows geralmente apresentam esses arquivos ao usuário por meio do sistema de arquivos do Windows e do Explorador de Arquivos. Antes do Windows 10, versão 1709, o suporte ao mecanismo de sincronização no Windows era limitado a superfícies ad-hoc independentes de cenário, como o painel de navegação do Explorador de Arquivos, a bandeja do sistema do Windows e (para aplicativos mais técnicos) drivers de filtro do sistema de arquivos.

A versão 1709 do Windows 10 (também chamada de Fall Creators Update) introduziu a API de arquivos de nuvem. Essa API é uma nova plataforma que formaliza o suporte para mecanismos de sincronização. A API de arquivos de nuvem fornece suporte para mecanismos de sincronização de uma maneira que oferece muitos novos benefícios para desenvolvedores e usuários finais.

A API de arquivos de nuvem contém as seguintes APIs nativas do Win32 e APIs do WinRT (Windows Runtime):

• API de Filtro de Nuvem: essa API nativa do Win32 fornece funcionalidade no marco de delimitação entre o modo de usuário e o sistema de arquivos. Essa API manipula a criação e o gerenciamento de arquivos e diretórios de espaço reservado.
• NamespaceWindows.Storage.Provider: essa API WinRT permite que os aplicativos configurem o provedor de armazenamento em nuvem e registrem a raiz de sincronização com o sistema operacional.

Observação

Atualmente, a API de arquivos em nuvem não oferece suporte à implementação de mecanismos de sincronização em nuvem em aplicativos UWP. Os mecanismos de sincronização na nuvem devem ser implementados em aplicativos da área de trabalho.

Recursos compatíveis

A API de arquivos de nuvem fornece os seguintes recursos para a criação de mecanismos de sincronização na nuvem.

Arquivos de espaço reservado

• Os mecanismos de sincronização podem criar arquivos de espaço reservado que consomem apenas 1 KB de armazenamento para o cabeçalho do sistema de arquivos e que se hidratam automaticamente em arquivos completos em condições normais de uso. Arquivos de espaço reservado presentes como arquivos típicos para aplicativos e para usuários finais no Windows Shell.
• Os arquivos de espaço reservado são integrados verticalmente do kernel do Windows até o Windows Shell, e a compatibilidade do aplicativo com arquivos de espaço reservado geralmente não é um problema. Se você usar APIs do sistema de arquivos, o Prompt de Comando ou uma área de trabalho ou um aplicativo UWP para acessar um arquivo de espaço reservado, o arquivo será hidratado sem alterações de código adicionais e esse aplicativo poderá usar o arquivo normalmente.
• Os arquivos podem existir em três estados:
  • Arquivo de espaço reservado: uma representação vazia do arquivo e disponível somente se o serviço de sincronização estiver disponível.
  • Arquivo completo: o arquivo foi hidratado implicitamente e pode ser desidratado pelo sistema se precisar de espaço.
  • Arquivo completo fixado: o arquivo foi hidratado explicitamente pelo usuário por meio do Explorador de Arquivos e tem a garantia de estar disponível offline.

A imagem a seguir demonstra como os estados de arquivo completo de espaço reservado, completo e fixo são exibidos no Explorador de Arquivos.

Registro raiz de sincronização padronizada

• O registro de uma raiz de sincronização é simples e padronizado. Isso inclui a criação de um nó de marca no painel de navegação do Explorador de Arquivos, conforme mostrado na captura de tela a seguir. As raízes podem ser criadas como entradas individuais de nível superior ou como filhos de um agrupamento pai.

  

Integração do shell

• Ícones de estado:
  • A API de arquivos de nuvem fornece ícones de estado de hidratação automática padronizados mostrados no Explorador de Arquivos e na área de trabalho do Windows.
  • Além dos ícones de estado padrão do Windows usados para o estado de hidratação, você pode fornecer ícones de estado personalizados para propriedades adicionais específicas do serviço.
  • Substitui as extensões do Shell de sobreposição de ícone herdado.
• Indicação de progresso:
  • A abertura de um arquivo de espaço reservado que leva mais de alguns segundos para se hidratar mostrará o progresso da hidratação. O progresso é mostrado em alguns locais, dependendo do contexto:
    • Em uma janela de diálogo do mecanismo de cópia.
    • O progresso embutido é mostrado ao lado do arquivo no Explorador de Arquivos.
    • Se o arquivo não for aberto de acordo com as instruções específicas do usuário, uma notificação do sistema será mostrada para informar o usuário e fornecer uma maneira de controlar a atividade de hidratação não intencional.
• Miniaturas e metadados:
  • Os arquivos de espaço reservado podem ter miniaturas avançadas fornecidas pelo serviço e metadados de arquivo estendidos para fornecer ao usuário uma experiência perfeita do Explorador de Arquivos.
• Painel de navegação do Explorador de Arquivos:
  • O registro de uma raiz de sincronização com a API de arquivos de nuvem faz com que essa raiz de sincronização (com um ícone e um nome personalizado) apareça no painel de navegação do Explorador de Arquivos.
• Menus de contexto do Explorador de Arquivos:
  • O registro de uma raiz de sincronização com a API de arquivos de nuvem fornece automaticamente vários verbos (entradas de menu) no menu de contexto do Explorador de Arquivos que permitem ao usuário controlar o estado de hidratação de seu arquivo.
  • Verbos adicionais podem ser adicionados a esta seção do menu de contexto usando APIs compatíveis com a Ponte de Desktop.
• Controle de usuário da hidratação do arquivo:
  • Os usuários estão sempre no controle da hidratação do arquivo, mesmo quando os arquivos não são hidratados explicitamente pelo usuário. Um brinde interativo é mostrado para hidratação de fundo para alertar o usuário e fornecer opções. A imagem a seguir demonstra uma notificação do sistema para um arquivo de hidratação.
  • Se um usuário bloquear um aplicativo de hidratar arquivos por meio de uma notificação do sistema interativa, ele poderá desbloquear o aplicativo na página Downloads automáticos de arquivos em Configurações.
• Conectando operações do mecanismo de cópia (com suporte no build 19624 do Windows 10 Insider Preview e versões posteriores):
  • Os provedores de armazenamento em nuvem podem registrar um gancho de cópia de shell para monitorar operações de arquivo em sua raiz de sincronização.
  • O provedor registra o gancho de cópia definindo o valor de registro CopyHook na chave do Registro raiz de sincronização para o CLSID de seu objeto de servidor local COM. Este objeto de servidor local implementa a interface IStorageProviderCopyHook.
• Compartilhamento de arquivos (com suporte na versão 21H2 do Windows 11 e versões posteriores):
  • Os provedores de armazenamento em nuvem podem registrar um manipulador de compartilhamento que será invocado quando o usuário selecionar o comando "Compartilhar" em um arquivo de nuvem na raiz de sincronização.
  • O provedor registra o manipulador de compartilhamento definindo o valor de registro ShareHandler na chave do Registro raiz de sincronização para o CLSID de seu objeto de servidor local COM. Este objeto de servidor local implementa a interface IExplorerCommand.

Ponte de Desktop

• Os mecanismos de sincronização usando as APIs de arquivos em nuvem são projetados para usar a Ponte de Desktop como um requisito de implementação.

Exemplo de Espelho de Nuvem

O exemplo de Espelho de Nuvem ilustra como criar uma solução que usa a API de arquivos de nuvem. Ele não se destina a ser usado como código de produção. Ele não tem um tratamento de erro robusto e é gravado para ser o mais facilmente compreendido possível. Ele se chama Espelho de Nuvem porque espelha uma pasta local em seu disco local. Especifique uma pasta de servidor destinada a representar o servidor de arquivos de nuvem e uma pasta de cliente destinada a especificar o caminho raiz da sincronização. Um nó de nível superior aparece no painel de navegação no Explorador de Arquivos chamado TestStorageProviderDisplayName e esse nó é mapeado para a pasta do cliente especificada.

Quando se trata de sincronização, essas são as coisas que um provedor de sincronização de arquivos de nuvem totalmente desenvolvido deve implementar:

• Quando o arquivo raiz de sincronização é apenas um espaço reservado, o serviço é responsável por copiar o conteúdo do arquivo para hidratação. Isso é implementado no exemplo.
• Quando o arquivo raiz de sincronização é um arquivo completo e o conteúdo do arquivo no serviço de nuvem é alterado, o serviço é responsável por notificar o cliente de sincronização local da alteração e o cliente de sincronização local deve lidar com mesclagens de acordo com suas próprias especificações. Isso não é implementado no exemplo.
• Quando o arquivo raiz de sincronização é um arquivo completo e o conteúdo do arquivo no caminho raiz de sincronização (o cliente local) é alterado, o cliente de sincronização local deve notificar o serviço de nuvem e manipular mesclagens de acordo com suas próprias especificações. A notificação de alteração de arquivo local é implementada no exemplo, mas não faz nada.

Usar o exemplo

1. Crie duas pastas no disco rígido local. Um deles atuará como o servidor e o outra como o cliente.
2. Adicione alguns arquivos à pasta do servidor. Verifique se a pasta do cliente está vazia.
3. Abra o exemplo de Espelho de Nuvem no Visual Studio. Defina o projeto CloudMirrorPackage como seu projeto de inicialização e, em seguida, compile e execute o exemplo. Quando solicitado pelo exemplo, insira os dois caminhos para o servidor e as pastas do cliente. Depois disso, você verá uma janela do console com informações de diagnóstico.
4. Abra o Explorador de Arquivos e confirme se o nó TestStorageProviderDisplayName e os espaços reservados são exibidos para todos os arquivos copiados na pasta do servidor. Para simular um aplicativo que tenta abrir arquivos sem usar o seletor, copie várias imagens para a pasta do servidor. Clique duas vezes em uma delas na pasta raiz de sincronização e confirme se ela se hidrata. Em seguida, abra o aplicativo Fotos. O aplicativo pré-carregará arquivos adjacentes em segundo plano para tornar mais provável que o usuário não tenha atrasos ao examinar as outras imagens. Você pode observar que a desidratação em segundo plano ocorre por meio de notificações do sistema ou no Explorador de Arquivos.
5. Clique com o botão direito do mouse em um arquivo no Explorador de Arquivos para preparar um menu de contexto e confirme se o item de menu TestCommand é exibido. Ao clicar neste item de menu, uma caixa de mensagem será exibida.
6. Para interromper o exemplo, defina o foco para a saída do console e pressione Ctrl-C. Isso limpará o registro raiz de sincronização para que o provedor seja desinstalado. Se o exemplo falhar, é possível que a raiz de sincronização permaneça registrada. Isso fará com que o Explorador de Arquivos seja relançado sempre que você clicar em qualquer coisa e você deverá solicitar os locais falsos do cliente e do servidor. Se isso ocorrer, desinstale o aplicativo de exemplo CloudMirrorPackage do seu computador.

Arquitetura de exemplo

O exemplo é deliberadamente simples. Ele usa classes estáticas para que seja desnecessário passar ponteiros de instância. Estas são as principais classes no exemplo:

• FakeCloudProvider: esta classe de nível superior controla as seguintes classes de trabalho:
  • CloudProviderRegistrar: registra as informações raiz de sincronização com o Windows Shell.
  • Espaços reservados: gera os arquivos de espaço reservado no caminho raiz de sincronização.
  • ShellServices: constrói os provedores do Windows Shell para o menu de contexto, miniaturas e outros serviços.
  • CloudProviderSyncRootWatcher: cria uma instância de um DirectoryWatcher para monitorar as alterações no caminho raiz de sincronização e agir com base nas alterações.
  • FileCopierWithProgress: copia arquivos da pasta do servidor para a pasta do cliente lentamente em partes para simular o download deles de um servidor de nuvem real. Fornece uma indicação de progresso para que o sistema e a interface do usuário do Explorador de Arquivos mostre ao usuário algo informativo.

Além das classes acima, o exemplo também fornece várias classes auxiliares para solicitar ao usuário pastas e alguns utilitários. TestExplorerCommandHandler, CustomStateProvider, ThumbnailProvider e UriSource são exemplos de provedores de serviços Shell.

Arquitetura da API de arquivos de nuvem

O núcleo da pilha de armazenamento na API de arquivos de nuvem tem um driver de minifiltro do sistema de arquivos chamado cldflt.sys. Esse driver atua como um proxy entre os aplicativos do usuário e o mecanismo de sincronização. Seu mecanismo de sincronização sabe como baixar e carregar os dados sob demanda enquanto é responsabilidade do cldflt.sys trabalhar com o Shell para apresentar arquivos como se os dados de nuvem estivessem disponíveis localmente.

Atualmente, o Cldflt.sys só dá suporte a volumes NTFS porque depende de alguns recursos exclusivos do NTFS.

Há muitos drivers de minifiltro do sistema de arquivos em um sistema e eles podem estar ativos em um determinado volume ao mesmo tempo. Os drivers que são mais interessantes para a API de arquivos de nuvem são os filtros do sistema de arquivos antivírus.

Os drivers de minifiltro do sistema de arquivos são gerenciados e suportados por um componente especial do modo kernel chamado gerenciador de filtros. Entre muitas outras tarefas, o gerenciador de filtros facilita a comunicação não filtrada entre filtros e componentes do modo de usuário por meio de um constructo conhecido como porta de mensagem de filtro.

Políticas de hidratação

O Windows dá suporte a diversas políticas de hidratação primária e modificadores de política de hidratação secundária. As políticas de hidratação primária têm esta ordem:

Sempre completa > Completa > Progressiva > Parcial

Aplicativos e mecanismos de sincronização podem definir sua política de hidratação primária preferencial. Se não for especificado, a política de hidratação padrão será progressiva para aplicativos e mecanismos de sincronização.

A política de hidratação de um arquivo de nuvem é determinada no tempo de abertura do arquivo por esta fórmula:

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

Por exemplo, digamos que o usuário esteja tentando abrir um arquivo PDF armazenado na Unidade de Nuvem Fabrikam usando o Visualizador de PDF Contoso, que não especifica uma política de hidratação preferencial. A política de hidratação do aplicativo é, portanto, a hidratação progressiva nesse caso por padrão. No entanto, como a Unidade de Nuvem Fabrikam é um mecanismo de sincronização de hidratação completa, a política de hidratação final no arquivo torna-se hidratação completa, o que resultará na hidratação completa do arquivo no primeiro acesso. O mesmo resultado ocorre nos casos em que o mecanismo de sincronização dá suporte à hidratação progressiva, mas a preferência do aplicativo é a hidratação completa.

Observe que a política de hidratação de arquivo não pode ser alterada depois que o arquivo é aberto.

Compatibilidade com aplicativos que usam pontos de nova análise

A API de arquivos de nuvem implementa o sistema de espaço reservado usando pontos de nova análise. Um equívoco comum sobre pontos de nova análise é que eles são iguais aos links simbólicos. Esse equívoco é refletido ocasionalmente nas implementações do aplicativo e, como resultado, muitos aplicativos existentes resultam em erros ao encontrar qualquer ponto de nova análise.

Para atenuar esse problema de compatibilidade, a API de arquivos de nuvem sempre oculta seus pontos de nova análise de todos os aplicativos, exceto para mecanismos de sincronização e processos cuja imagem principal resida em %systemroot%. Aplicativos que entendem os pontos de nova análise corretamente podem forçar a plataforma a expor pontos de nova análise da API de arquivos de nuvem usando RtlSetProcessPlaceholderCompatibilityMode ou RtlSetThreadProcessPlaceholderCompatibilityMode.