Compartilhar via

Acessar dados em documentos no servidor

Você pode programar com base nos dados numa personalização em nível de documento sem ter que usar o modelo de objeto do Microsoft Office Word ou do Microsoft Office Excel. Isso significa que você pode acessar dados contidos em um documento em um servidor que não tem o Word ou o Excel instalados. Por exemplo, o código em um servidor (por exemplo, em uma página ASP.NET) pode personalizar os dados em um documento e enviar o documento personalizado para um usuário final. Quando o usuário final abre o documento, o código de associação de dados no assembly da solução associa os dados personalizados ao documento. Isso é possível porque os dados no documento são separados da interface do usuário. Para mais informações, consulte dados em cache em personalizações de nível de documento.

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.

Armazenar dados em cache para uso em um servidor

Para armazenar em cache um objeto de dados em um documento, marque-o com o atributo CachedAttribute em tempo de design ou use o método StartCaching de um item de host em tempo de execução. Quando você armazena em cache um objeto de dados em um documento, o runtime das Ferramentas do Visual Studio para Office serializa o objeto em uma cadeia de caracteres XML armazenada no documento. Os objetos devem atender a determinados requisitos para serem qualificados para armazenamento em cache. Para obter mais informações, consulte os dados do Cache.

O código do lado do servidor pode manipular quaisquer objetos de dados no cache de dados. Os controles associados a instâncias de dados armazenadas em cache são sincronizados com a interface do usuário, de modo que todas as alterações do lado do servidor feitas nos dados sejam exibidas automaticamente quando o documento for aberto no cliente.

Acessar dados no cache

Você pode acessar dados no cache de aplicativos fora do Office, por exemplo, de um aplicativo de console, de um aplicativo do Windows Forms ou de uma página da Web. O aplicativo que acessa os dados armazenados em cache deve ter total confiança; um aplicativo Web que tenha confiança parcial não pode inserir, recuperar ou alterar dados armazenados em cache em um documento do Office.

O cache de dados é acessível por meio de uma hierarquia de coleções expostas pela CachedData propriedade da ServerDocument classe:

  • A propriedade CachedData retorna um CachedData, que contém todos os dados armazenados em cache de uma personalização em nível de documento.

  • Cada CachedData contém um ou mais objetos CachedDataHostItem. Um CachedDataHostItem contém todos os objetos de dados armazenados em cache definidos em uma única classe.

  • Cada CachedDataHostItem contém um ou mais objetos CachedDataItem. Um CachedDataItem representa um único objeto de dados armazenado em cache.

    O exemplo de código a seguir demonstra como acessar uma cadeia de caracteres armazenada em cache na Sheet1 classe de um projeto de pasta de trabalho do Excel. Este exemplo faz parte de um exemplo maior fornecido para o Save método.

    serverDocument1 = new ServerDocument(documentPath);
CachedDataHostItem hostItem1 = 
    serverDocument1.CachedData.HostItems["ExcelWorkbook1.Sheet1"];
CachedDataItem dataItem1 = hostItem1.CachedData["CachedString"];

Modificar dados no cache

Para modificar um objeto de dados armazenado em cache, você normalmente executa as seguintes etapas:

  1. Desserialize a representação XML do objeto armazenado em cache em uma nova instância do objeto. Você pode acessar o XML usando a Xml propriedade do CachedDataItem que representa o objeto de dados armazenado em cache.

  2. Faça as alterações nessa cópia.

  3. Serialize o objeto alterado novamente no cache de dados usando uma das seguintes opções:

    • Se você quiser serializar automaticamente as alterações, use o SerializeDataInstance método. Esse método usa o formato DiffGram para serializar DataSet, DataTable e objetos de conjunto de dados tipados no cache de dados. O formato DiffGram garante que as alterações no cache de dados em um documento offline sejam enviadas ao servidor corretamente.

    • Se você quiser executar sua própria serialização para as alterações nos dados armazenados em cache, poderá gravar diretamente na propriedade Xml. Especifique o formato DiffGram se você usar um DataAdapter para atualizar um banco de dados com alterações feitas nos dados em um DataSet conjunto de dados ou conjunto de dados digitado DataTable. Caso contrário, o DataAdapter banco de dados será atualizado adicionando novas linhas em vez de modificar linhas existentes.

Modificar dados sem desserializar o valor atual

Em alguns casos, talvez você queira modificar o valor do objeto armazenado em cache sem primeiro desserializar o valor atual. Por exemplo, você pode fazer isso se estiver alterando o valor de um objeto que tem um tipo simples, como uma cadeia de caracteres ou um inteiro, ou se estiver inicializando um cache DataSet em um documento em um servidor. Nesses casos, você pode usar o SerializeDataInstance método sem primeiro desserializar o valor atual do objeto armazenado em cache.

O exemplo de código a seguir demonstra como alterar o valor de uma cadeia de caracteres armazenada em cache na Sheet1 classe de um projeto de pasta de trabalho do Excel. Este exemplo faz parte de um exemplo maior fornecido para o Save método.

serverDocument1 = new ServerDocument(documentPath);
CachedDataHostItem hostItem1 = 
    serverDocument1.CachedData.HostItems["ExcelWorkbook1.Sheet1"];
CachedDataItem dataItem1 = hostItem1.CachedData["CachedString"];

if (dataItem1 != null &&
    Type.GetType(dataItem1.DataType) == typeof(string))
{
    dataItem1.SerializeDataInstance("This is the new cached string value.");
    serverDocument1.Save();
}

Modificar valores nulos no cache de dados

O cache de dados não armazena objetos que têm o valor nulo quando o documento é salvo e fechado. Essa limitação tem várias consequências ao modificar dados armazenados em cache:

  • Se você definir qualquer objeto no cache de dados como o valor nulo, todos os objetos no cache de dados serão automaticamente definidos como nulos quando o documento for aberto e todo o cache de dados será limpo quando o documento for salvo e fechado. Ou seja, todos os objetos armazenados em cache serão removidos do cache de dados e a CachedData coleção estará vazia.

  • Se você criar uma solução com objetos nulos no cache de dados e quiser inicializar esses objetos usando a ServerDocument classe antes que o documento seja aberto pela primeira vez, deverá garantir que você inicialize todos os objetos no cache de dados. Se você inicializar apenas alguns dos objetos, todos os objetos serão definidos como nulos quando o documento for aberto e todo o cache de dados será limpo quando o documento for salvo e fechado.

Acessar conjuntos de dados tipados no cache

Se você quiser acessar os dados em um conjunto de dados digitado de uma solução do Office e de um aplicativo fora do Office, como um aplicativo do Windows Forms ou um projeto ASP.NET, deverá definir o conjunto de dados digitado em um assembly separado referenciado em ambos os projetos. Se você adicionar o conjunto de dados tipado a cada projeto usando o assistente de Configuração da Fonte de Dados ou o Designer de Conjunto de Dados, o .NET Framework tratará os conjuntos de dados tipados nos dois projetos como tipos diferentes. Para obter mais informações sobre como criar conjuntos de dados tipados, consulte Criar e configurar conjuntos de dados no Visual Studio.

Conteúdo relacionado

  • Last updated on