Crie um mecanismo de sincronização na nuvem que ofereça suporte a ficheiros 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ários, 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.

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

A API de arquivos na nuvem contém as seguintes APIs nativas do Win32 e APIs do Tempo de Execução do Windows (WinRT):

• Cloud Filter API: Esta API Win32 nativa fornece funcionalidade no limite entre o modo de usuário e o sistema de arquivos. Essa API lida com a criação e o gerenciamento de arquivos e diretórios de espaço reservado.
• Namespace Windows.Storage.Provider: essa API do WinRT permite que os aplicativos configurem o provedor de armazenamento em nuvem e registrem a raiz de sincronização com o sistema operacional.

Funcionalidades suportadas

A API de arquivos na 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 fictícios que consomem apenas 1 KB de armazenamento para o cabeçalho do sistema de arquivos e que se transformam automaticamente em arquivos completos em condições normais de uso. Os arquivos de espaço reservado aparecem para aplicativos e usuários finais como arquivos típicos no Shell do Windows.
• Os arquivos de espaço reservado são integrados verticalmente do kernel do Windows até o Shell do Windows, e a compatibilidade do aplicativo com arquivos de espaço reservado geralmente não é um problema. Quer utilize APIs do sistema de ficheiros, o Prompt de Comando, uma aplicação de ambiente de trabalho ou uma aplicação UWP para aceder a um ficheiro marcador, o ficheiro será hidratado sem necessidade de alterações adicionais no código, e essa aplicação poderá utilizá-lo 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.
  • Ficheiro completo: O ficheiro foi hidratado implicitamente e pode ser desidratado pelo sistema se o sistema precisar de espaço.
  • Arquivo completo fixo: O ficheiro foi hidratado explicitamente pelo utilizador através do Explorador de Ficheiros e está garantido que estará disponível offline.

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

Registo raiz de sincronização padronizado

• Registrar uma raiz de sincronização é simples e padronizada. Isso inclui a criação de um nó com 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 grupo pai.

  

Integração no shell

• Ícones de estado:
  • A API de arquivos na nuvem fornece ícones de estado de hidratação padronizados e automáticos 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 Shell de sobreposição de ícone herdadas.
• Indicação dos progressos:
  • Abrir um ficheiro de espaço reservado que demora mais de alguns segundos para se hidratar vai 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 em linha é mostrado ao lado do ficheiro no Explorador de Ficheiros.
    • Se o ficheiro não for aberto de acordo com as instruções específicas do utilizador, uma notificação de alerta será mostrada para informar o utilizador e fornecer um meio 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 proporcionar ao usuário uma experiência integrada no Explorador de Arquivos.
• Painel de navegação do Explorador de Ficheiros:
  • Registrar uma raiz de sincronização com a API de arquivos na 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 Ficheiros:
  • Registrar uma raiz de sincronização com a API de arquivos na 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 o Desktop Bridge.
• Controle de usuário de hidratação de 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 de brinde para um ficheiro sendo atualizado.
  • Se um utilizador bloquear uma aplicação de hidratar ficheiros através de uma notificação interativa, poderá desbloquear a aplicação na página Downloads automáticos de ficheiros em Configurações.
• Intercepção de operações do motor de cópia (suportadas no Windows 10 Insider Preview Build 19624 e versões posteriores):
  • Os provedores de armazenamento em nuvem podem registrar um mecanismo de cópia do shell para monitorar operações de arquivos na sua pasta raiz de sincronização.
  • O fornecedor regista o seu gancho de cópia definindo o valor de registo CopyHook na chave de registo da raiz de sincronização para o CLSID do seu objeto de servidor local COM. Este objeto de servidor local implementa a interface IStorageProviderCopyHook .
• Partilha de ficheiros (suportada 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 sob sua raiz de sincronização.
  • O fornecedor regista o seu manipulador de partilha definindo o valor do registo ShareHandler debaixo da sua chave de registo root de sincronização para o CLSID do seu objeto de servidor local COM. Este objeto de servidor local implementa a interface IExplorerCommand .

Bridge de Ambiente de Trabalho

• Os mecanismos de sincronização que usam as APIs de arquivos na nuvem são projetados para usar o Desktop Bridge como um requisito de implementação.

Exemplo de Cloud Mirror

O exemplo do Cloud Mirror ilustra como criar uma solução que usa a API de arquivos na nuvem. Não se destina a ser utilizado como código de produção. Carece de um tratamento robusto de erros e está escrito para ser o mais facilmente compreendido possível. Chama-se Cloud Mirror porque simplesmente espelha uma pasta local no seu disco local. Você especifica uma pasta de servidor destinada a representar seu servidor de arquivos na nuvem e uma pasta de cliente destinada a especificar o caminho raiz de sincronização. Um nó de nível superior chamado TestStorageProviderDisplayName aparece na janela de navegação no Explorador de Ficheiros, e este nó é mapeado para a pasta especificada do cliente.

Quando se trata de sincronização, estas são as coisas que um provedor de sincronização de arquivos na 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 na amostra.
• 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 na amostra.
• 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 lidar com 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.

Use o exemplo

1. Crie duas pastas no seu disco rígido local. Um deles atuará como servidor e o outro como 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, crie e execute o exemplo. Quando solicitado pelo exemplo, insira os dois caminhos para as pastas do servidor e do cliente. Depois disso, você verá uma janela do console com informações de diagnóstico.
4. Abra o Explorador de Arquivos e confirme que você vê o nó TestStorageProviderDisplayName e os espaços reservados para todos os arquivos copiados para a 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 um deles na pasta raiz de sincronização e confirme se ele se hidrata. Em seguida, abra o aplicativo Fotos. O aplicativo irá pré-carregar arquivos adjacentes em segundo plano para tornar mais provável que o usuário não experimente atrasos ao olhar através das outras imagens. Você pode observar a desidratação em segundo plano acontecer através de notificações ou no Explorador de Ficheiros.
5. Clique com o botão direito do rato num ficheiro no Explorador de Ficheiros para abrir um menu de contexto e confirme que vê o item de menu TestCommand . Clicar neste item de menu exibirá uma caixa de mensagem.
6. Para parar 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 registada. Isso fará com que o Explorador de Arquivos seja reiniciado toda vez que você clicar em qualquer coisa, e você será solicitado para os falsos locais de cliente e servidor. Se isso ocorrer, desinstale o aplicativo de exemplo CloudMirrorPackage do seu computador.

Arquitetura de exemplo

A amostra é deliberadamente simples. Ele usa classes estáticas para tornar desnecessário passar ponteiros de instância. Aqui estão as principais classes no exemplo:

• FakeCloudProvider: Esta classe de nível superior controla as seguintes classes de trabalho:
  • CloudProviderRegistrar: registra as informações de raiz de sincronização com o Shell do Windows.
  • Espaços reservados: Gera os arquivos de espaços reservados no caminho raiz da sincronização.
  • ShellServices: Constrói os provedores do Shell do Windows para o menu de contexto, miniaturas e outros serviços.
  • CloudProviderSyncRootWatcher: Instancia um DirectoryWatcher para monitorar 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. Fornece indicação de progresso para que os alertas e a interface do usuário do Explorador de Arquivos mostrem ao utilizador 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 na nuvem

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

Cldflt.sys atualmente só suporta volumes NTFS porque depende de alguns recursos exclusivos do NTFS.

Existem muitos drivers de minifiltro de sistema de arquivos em um sistema e eles podem estar ativos em um determinado volume ao mesmo tempo. Os drivers que são de maior interesse para a API de arquivos na 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 de modo kernel chamado gerenciador de filtros. Entre muitas outras funções, o gerenciador de filtros facilita a comunicação não filtrada entre filtros e componentes do modo de usuário por meio de uma construção conhecida como porta de mensagem de filtro.

Políticas de Hidratação

O Windows suporta uma variedade de 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 completo > Completo > Progressivo > Parcial

Tanto os aplicativos quanto os mecanismos de sincronização podem definir sua política de hidratação primária preferida. Se não for especificada, 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 na nuvem é determinada no momento 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 Contoso PDF Viewer, que não especifica uma política de hidratação preferida. A política de hidratação da aplicação é, portanto, hidratação progressiva, neste caso por defeito. No entanto, como o Fabrikam Cloud Drive é um motor de sincronização de hidratação completa, a política de hidratação final para o ficheiro torna-se hidratação completa, o que fará com que o ficheiro seja inteiramente hidratado assim que for acedido pela primeira vez. O mesmo resultado acontece nos casos em que o mecanismo de sincronização suporta hidratação progressiva, mas a preferência do aplicativo é a hidratação completa.

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

Compatibilidade com aplicações que usam pontos de reanálise

A API de arquivos na nuvem implementa o sistema de espaço reservado usando pontos de análise. Um equívoco comum sobre os pontos de reanálise é que eles são iguais a ligações simbólicas. Esse equívoco é ocasionalmente refletido em implementações de aplicações e, como resultado, muitas aplicações existentes apresentam erros ao encontrar qualquer ponto de reanálise.

Para atenuar esse problema de compatibilidade, a API de ficheiros na nuvem sempre oculta os seus pontos de reanálise de todos os aplicativos, exceto motores de sincronização e processos cuja imagem principal esteja localizada em %systemroot%. As aplicações que compreendem corretamente os pontos de reanálise podem forçar a plataforma a expor pontos de reanálise da API de ficheiros na nuvem usando RtlSetProcessPlaceholderCompatibilityMode ou RtlSetThreadProcessPlaceholderCompatibilityMode.

Pesquisa de ficheiros na nuvem

A pesquisa de ficheiros na nuvem é suportada no Windows 11, versão 24H2 e em versões posteriores em PCs Copilot+ ou PCs na Nuvem com IA. Os seguintes recursos estão disponíveis para os provedores de armazenamento em nuvem se integrarem à experiência do Windows Search:

• Os provedores de armazenamento em nuvem podem registrar um manipulador de pesquisa de arquivos para sua raiz de sincronização, permitindo que contribuam com resultados de pesquisa para o Explorador de Arquivos e o Windows Search.
• Os provedores de armazenamento em nuvem registam um handler de pesquisa ao definir o valor de registo SearchHandlerFactory sob a sua chave de registo raiz de sincronização para o CLSID do 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 do Windows Search chama o método Find durante uma pesquisa, mesclando seus resultados com os do indexador de pesquisa local.

Conteúdo relacionado

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

IStorageProviderSearchHandlerFactory

Namespace Windows.Storage.Provider