Desenvolver um mecanismo de sincronização de nuvem que dê suporte a arquivos de marcador

Um mecanismo de sincronização é um serviço que sincroniza arquivos, normalmente entre um host remoto e um cliente local. 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 Windows e (para aplicativos mais técnicos) drivers de filtro do sistema de arquivos.

O Windows 10 versão 1709 (também chamado 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 limite 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.
• Namespace Windows.Storage.Provider: Esta 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 de nuvem não dá suporte à implementação de mecanismos de sincronização de nuvem em aplicativos UWP. Os mecanismos de sincronização de nuvem devem ser implementados em aplicativos da área de trabalho.

Recursos com suporte

A API de arquivos de nuvem fornece os seguintes recursos para a criação de mecanismos de sincronização de 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 atuam como arquivos típicos para aplicativos e 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, um aplicativo de desktop 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 for necessário 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 completos, completos e fixados são mostrados no Explorador de Arquivos.

Registro padronizado da raiz de sincronização

• Registrar uma raiz de sincronização é simples e padronizado. Isso inclui a criação de um nó personalizado no painel de navegação do Explorador de Arquivos, como 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 de Shell de sobreposição de ícones legados.
• Indicação de progresso:
  • Ao abrir um arquivo temporário que demora mais de alguns segundos para ser hidratado, será exibido o progresso da hidratação. O progresso é mostrado em alguns locais, dependendo do contexto:
    • Em uma janela de diálogo do motor de cópia.
    • O progresso em linha é mostrado ao lado do arquivo no Explorador de Arquivos.
    • Se o arquivo não for aberto na instrução específica 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 placeholder podem ter miniaturas avançadas fornecidas pelo serviço e metadados de arquivo estendidos para fornecer ao usuário uma experiência perfeita no File Explorer.
• Painel de navegação do Explorador de Arquivos:
  • Registrar 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:
  • Registrar 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 extras podem ser adicionados a esta seção do menu de contexto usando APIs compatíveis com Desktop Bridge.
• Controle do 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 toast interativo é exibido para hidratação em segundo plano, alertando o usuário e fornecendo opções. A imagem a seguir demonstra uma notificação toast para um arquivo de hidratação.
  • Se um usuário bloquear um aplicativo de hidratação de arquivos por meio de um toast interativo, 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 Windows 10 Insider Preview Build 19624 e versões posteriores):
  • Os provedores de armazenamento em nuvem podem registrar um gancho de cópia do shell para monitorar operações de arquivo dentro de seu diretório raiz de sincronização.
  • O provedor registra o gancho de cópia definindo o valor do 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 no Windows 11 versão 21H2 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 seu manipulador de compartilhamento definindo o valor do registro do ShareHandler em sua chave de 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

• Mecanismos de sincronização usando as APIs de arquivos de nuvem foram projetados para usar a Ponte de Área de Trabalho como um requisito de implementação.

Exemplo de Espelho de Nuvem

O exemplo do Cloud Mirror 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 é escrito para ser o mais facilmente compreendido possível. Ele se chama Cloud Mirror porque ele simplesmente 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.

Utilize o exemplo

1. Crie duas pastas no disco rígido local. Um deles atuará como o servidor e o outro como o cliente.
2. Adicione alguns arquivos à pasta do servidor. Verifique se a pasta do cliente está vazia.
3. Abra o exemplo do Cloud Mirror 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 você vê o nó TestStorageProviderDisplayName e os espaços reservados 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 a desidratação em segundo plano acontecer por meio de notificações ou no Explorador de Arquivos.
5. Clique com o botão direito do mouse em um arquivo no Explorador de Arquivos para abrir um menu de contexto e confirme se você vê o item de menu TestCommand . Clicar neste item de menu exibirá uma caixa de mensagem.
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 a amostra 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ê será solicitado a 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 não seja necessá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ços reservados 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 sobre as 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. Oferece uma indicação de progresso, permitindo que as notificações do sistema e a interface do usuário do Explorador de Arquivos mostrem algo informativo ao usuário.

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 todos exemplos de provedores de serviços Shell.

Arquitetura da API de arquivos de nuvem

No núcleo da arquitetura de armazenamento na API de arquivos em nuvem, há 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.

Cldflt.sys atualmente 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 uma variedade de políticas primárias de hidratação 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 no Fabrikam Cloud Drive 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, hidratação progressiva, nesse caso por padrão. No entanto, como o Fabrikam Cloud Drive utiliza um mecanismo de sincronização de hidratação completa, a política final de hidratação do arquivo torna-se hidratação completa, o que resultará no arquivo sendo totalmente hidratado 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 é hidratação total.

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 reanálise

A API de arquivos de nuvem implementa o sistema de espaço reservado usando pontos de reanálise. Um equívoco comum sobre pontos de reanálise é que eles são iguais aos links simbólicos. Esse equívoco é ocasionalmente refletido nas implementações de aplicações e, como resultado, muitas aplicações existentes enfrentam erros quando encontram qualquer ponto de reanálise.

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

Pesquisa de arquivos de nuvem

Há suporte para a pesquisa de arquivos de nuvem no Windows 11, versão 24H2 e posterior em PCs Copilot+. Os seguintes recursos estão disponíveis para que os provedores de armazenamento em nuvem se integrem à experiência de Pesquisa do Windows:

• Os provedores de armazenamento em nuvem podem registrar um manipulador de pesquisa de arquivos no ponto principal de sincronização, permitindo-lhes contribuir com resultados de pesquisa para o Explorador de Arquivos e a Pesquisa do Windows.
• Os provedores de armazenamento em nuvem registram um manipulador de pesquisa definindo o valor do registro SearchHandlerFactory em sua chave de registro raiz de sincronização para o CLSID de seu objeto de servidor local COM. Este objeto de servidor local implementa a interface IStorageProviderSearchHandlerFactory .
• O IStorageProviderSearchHandlerFactory cria uma implementação de IStorageProviderSearchHandler. Essa implementação IStorageProviderSearchHandler chama o serviço de pesquisa do provedor de nuvem para pesquisar arquivos que podem não estar disponíveis localmente no dispositivo.
• A experiência de Pesquisa do Windows chama o método Find durante uma pesquisa, mesclando seus resultados com aqueles do indexador de pesquisa local.

Conteúdo relacionado

Integração do provedor de arquivos de nuvem com o Windows Search

IStorageProviderSearchHandlerFactory

Namespace Windows.Storage.Provider