Dados de cache

Você pode armazenar em cache objetos de dados em uma personalização em nível de 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 Recursos disponíveis por aplicativo e tipo de projeto do Office.

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 StartCaching método de um item de host, como as ThisDocument classes 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 objetos de dados a serem 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 uma propriedade de um item de host, como as ThisDocument classes ou ThisWorkbook .

• 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 executar 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 retornar interfaces de propriedades e campos.

• Não implementar IDictionary se uma coleção.

  Quando você armazena em cache um objeto de dados, o tempo de execução do Visual Studio Tools for Office serializa o objeto em uma cadeia de caracteres XML que é armazenada em uma parte XML personalizada no documento. Para obter mais informações, consulte 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 para o 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.

  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 é alterado. Para obter exemplos de código que demonstram como implementar ICachedTypeo , consulte a ControlCollection classe no exemplo de controles dinâmicos do Excel e no exemplo de controles dinâmicos do Word em exemplos de desenvolvimento do Office e instruções passo a passo.

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

Se você armazenar em cache objetos de dados em um documento protegido com uma senha, as alterações nos dados armazenados em cache não serão salvas. Você pode salvar as 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, reaplique 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 com 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 tempo de execução do Visual Studio Tools for 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 atributo em tempo de design, poderá usar a ServerDocument classe para inicializar os objetos de dados armazenados em cache antes que o CachedAttribute documento seja aberto. Isso é útil se você deseja inicializar os dados armazenados em cache em um servidor sem o Word ou 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 em cache dados para uso offline ou em um servidor
• Como: armazenar em cache programaticamente uma fonte de dados em um documento do Office
• Como armazenar dados em cache em um documento protegido por senha
• Demonstra Passo a passo: Criar uma relação de detalhes mestre usando um conjunto de dados armazenado em cache