Dados de cache

Você pode armazenar objetos de dados em cache em uma personalização no nível do documento para que os dados possam ser acessados offline ou sem abrir o Microsoft Office Word ou o Microsoft Office Excel. Para armazenar em cache um objeto, o objeto deve ter um tipo de dados que atenda a determinados requisitos. Muitos tipos de dados comuns no .NET Framework atendem a esses requisitos, incluindo String, DataSete DataTable.

Aplica-se a: As informações neste tópico se aplicam a projetos de nível de documento para Excel e Word. Para obter mais informações, consulte Os recursos disponíveis pelo aplicativo do Office e pelo tipo de projeto.

Há duas maneiras de adicionar um objeto ao cache de dados:

• Para adicionar um objeto ao cache de dados quando a solução for criada, aplique o CachedAttribute atributo à declaração de objeto. Para obter mais informações, consulte Como armazenar em cache dados para uso offline ou em um servidor.

• Para adicionar programaticamente um objeto ao cache de dados em tempo de execução, use o método de um item hospedeiro, como as classes ThisDocument ou ThisWorkbook. Para obter mais informações, consulte Como armazenar em cache programaticamente uma fonte de dados em um documento do Office.

  Depois de adicionar um objeto ao cache de dados, você pode acessar e modificar os dados armazenados em cache sem iniciar o Word ou o Excel. Para obter mais informações, consulte Acessar dados em documentos no servidor.

Requisitos para que objetos de dados sejam armazenados em cache

Para armazenar em cache um objeto de dados em sua solução, o objeto deve atender a estes requisitos:

• Seja um campo público de leitura/gravação ou propriedade de um item de host, como as ThisDocument ou ThisWorkbook classes.

• Não ser um indexador ou outra propriedade parametrizada.

  Além disso, o objeto de dados deve ser serializável pela classe, o XmlSerializer que significa que o tipo do objeto deve ter estas características:

• Seja um tipo público.

• Tenha um construtor público sem parâmetros.

• Não execute um código que exija privilégios de segurança adicionais.

• Exponha somente propriedades públicas de leitura/gravação (outras propriedades serão ignoradas).

• Não exponha matrizes multidimensionais (matrizes aninhadas são aceitas).

• Não retorne interfaces de propriedades e campos.

• Não implemente IDictionary se for uma coleção.

  Quando você armazena em cache um objeto de dados, o runtime das Ferramentas do Visual Studio para Office serializa o objeto em uma cadeia de caracteres XML armazenada em uma parte XML personalizada no documento. Para obter mais informações, consulte a visão geral de partes XML personalizadas.

Limites de tamanho de dados armazenados em cache

Há alguns limites para a quantidade total de dados que você pode adicionar ao cache de dados em um documento e ao tamanho de qualquer objeto individual no cache de dados. Se você exceder esses limites, o aplicativo poderá fechar inesperadamente quando os dados forem salvos no cache de dados.

Para evitar esses limites, siga estas diretrizes:

• Não adicione nenhum objeto maior que 10 MB ao cache de dados.

• Não adicione mais de 100 MB de dados totais ao cache de dados em um único documento.

  Esses são valores aproximados. Os limites exatos dependem de vários fatores, incluindo a RAM disponível e o número de processos em execução.

Controlar o comportamento de objetos armazenados em cache

Para obter mais controle sobre o comportamento de um objeto armazenado em cache, você pode implementar a ICachedType interface no tipo do objeto armazenado em cache. Por exemplo, você pode implementar essa interface se quiser controlar como o usuário é notificado quando o objeto foi alterado. Para obter exemplos de código que demonstram como implementar ICachedType, consulte a classe ControlCollection no Exemplo de Controles Dinâmicos do Excel e no Exemplo de Controles Dinâmicos do Word em exemplos e tutoriais de desenvolvimento do Office.

Persistir alterações nos dados armazenados em cache em documentos protegidos por senha

Se você armazenar objetos de dados em cache em um documento protegido com uma senha, as alterações nos dados armazenados em cache não serão salvas. Você pode salvar alterações nos dados armazenados em cache substituindo dois métodos. Substitua esses métodos para remover temporariamente a proteção quando o documento for salvo e, em seguida, reaplicar a proteção após a conclusão da operação de salvamento.

Para obter mais informações, consulte Como armazenar dados em cache em um documento protegido por senha.

Impedir a perda de dados ao adicionar valores nulos ao cache de dados

Quando você adiciona objetos ao cache de dados, todos os objetos armazenados em cache devem ser inicializados para um valor não nulo antes que o documento seja salvo e fechado. Se qualquer objeto armazenado em cache tiver um valor nulo quando o documento for salvo e fechado, o runtime das Ferramentas do Visual Studio para Office removerá automaticamente todos os objetos armazenados em cache do cache de dados.

Se você adicionar um objeto com um valor nulo ao cache de dados usando o CachedAttribute atributo em tempo de design, poderá usar a ServerDocument classe para inicializar os objetos de dados armazenados em cache antes que o documento seja aberto. Isso é útil se você quiser inicializar os dados armazenados em cache em um servidor sem o Word ou o Excel instalado, antes que o documento seja aberto por um usuário final. Para obter mais informações, consulte Acessar dados em documentos no servidor.

Conteúdo relacionado

• Como armazenar dados em cache para uso offline ou em um servidor
• Como armazenar em cache de forma programática uma fonte de dados em um documento do Office
• Como armazenar dados em cache em um documento protegido por senha
• Passo a passo: criar uma relação de detalhes mestre usando um conjunto de dados armazenado em cache