Acesso a dados em documentos no servidor

Artigo
08/08/2011

Você pode programar os dados em uma personalização no nível do documento sem ter que usar o modelo de objeto de Microsoft Office o Word ou Excel de Microsoft Office. Isso significa que você pode acessar os dados contidos em um documento em um servidor que não tem o Word ou Excel instalado. Por exemplo, o código em um servidor (por exemplo, em um ASP.NET página) pode personalizar os dados em um documento e envie o documento personalizado para um usuário final. Quando o usuário final abre o documento, o código de ligação de dados no conjunto de solução vincula os dados personalizados no documento. Isso é possível porque os dados no documento são separados da interface do usuário. For more information, see Dados armazenados em cache no nível do documento personalizações.

Aplicável a: As informações neste tópico se aplicam a projetos de nível de documento para os seguintes aplicativos: Excel 2007 e Excel 2010; Word 2007 e Word 2010. Para obter mais informações, consulte Recursos disponíveis pelo aplicativo do Office e o tipo de projeto.

Cache de dados para uso em um servidor.

Armazenar em cache um objeto de dados em um documento, marcá-lo com o CachedAttribute de atributo em tempo de design ou usar o StartCaching o método de um item de host em tempo de execução. Quando você armazena em cache um objeto de dados em um documento, o Visual Studio Tools for Office runtime serializa o objeto em uma string XML que está armazenada no documento. Objetos devem atender a certos requisitos para estar qualificado para armazenamento em cache. For more information, see Cache de dados.

O código do lado do servidor pode manipular quaisquer objetos de dados no cache de dados. Controles ligados a dados em cache instâncias são sincronizados com a interface do usuário, para que as alterações do lado do servidor são feitas nos dados aparecem automaticamente quando o documento é aberto no cliente.

Acesso a dados no Cache

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

O cache de dados está acessível através de uma hierarquia de coleções que é exposta pelo CachedData propriedade da ServerDocument classe:

O CachedData propriedade retorna um Microsoft.VisualStudio.Tools.Applications.CachedData, que contém todos os dados armazenados em cache em uma personalização no nível do documento.
Cada Microsoft.VisualStudio.Tools.Applications.CachedData contém um ou mais CachedDataHostItem objetos. A CachedDataHostItem contém todos os dados armazenados em cache objetos que são definidos dentro de uma única classe.
Cada CachedDataHostItem contém um ou mais CachedDataItem objetos. A CachedDataItem representa um objeto único dados armazenados em cache.

O exemplo de código a seguir demonstra como acessar uma seqüência de caracteres armazenados em cache na Sheet1 a classe de um projeto de pasta de trabalho do Excel. Este exemplo é parte de um exemplo maior, que é fornecido para o ServerDocument.Save método.

serverDocument1 = New ServerDocument(documentPath)
Dim hostItem1 As CachedDataHostItem = _
    serverDocument1.CachedData.HostItems("ExcelWorkbook1.Sheet1")
Dim dataItem1 As CachedDataItem = hostItem1.CachedData("CachedString")

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

Para obter um exemplo de código que demonstra como acessar os dados em um cache DataSet, consulte Como: Recuperar dados em cache a partir de uma pasta de trabalho em um servidor.

Modificando dados em Cache

Para modificar um objeto de dados em cache, normalmente, execute as seguintes etapas:

Desserializar a representação XML do objeto em cache em uma nova instância do objeto. Você pode acessar o XML usando o Xml propriedade da CachedDataItem que representa o objeto de dados em cache.
Faça as alterações dessa cópia.
Serialize o objeto alterado volta para o cache de dados usando uma das seguintes opções:
- Se você deseja serializar automaticamente as alterações, use o SerializeDataInstance método. Esse método usa o DiffGram formato de serialização DataSet, DataTablee digitou objetos dataset em cache de dados. O DiffGram formato garante que as alterações para o cache de dados em um documento off-line são enviadas ao servidor corretamente. For more information, see DiffGrams (ADO.NET).
- Se você quiser executar seu próprio de serialização para alterações de dados em cache, você pode escrever diretamente para o Xml propriedade. Especificar o DiffGram Formatar se você usar um DataAdapter para atualizar um banco de dados com as alterações feitas nos dados de um DataSet, DataTable, ou digitado dataset. Caso contrário, o DataAdapter atualizará o banco de dados, adicionando novas linhas em vez de modificar linhas existentes.

Para obter um exemplo de código que demonstra como serializar alterações em um objeto de dados em cache, escrevendo diretamente para o Xml propriedade, consulte Como: Alterar dados em uma pasta de trabalho em um servidor de cache.

A modificação de dados sem o valor atual de desserialização

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

O exemplo de código a seguir demonstra como alterar o valor de uma seqüência de caracteres armazenados em cache na Sheet1 a classe de um projeto de pasta de trabalho do Excel. Este exemplo é parte de um exemplo maior, que é fornecido para o ServerDocument.Save método.

serverDocument1 = New ServerDocument(documentPath)
Dim hostItem1 As CachedDataHostItem = _
    serverDocument1.CachedData.HostItems("ExcelWorkbook1.Sheet1")
Dim dataItem1 As CachedDataItem = hostItem1.CachedData("CachedString")

If dataItem1 IsNot Nothing AndAlso _
    Type.GetType(dataItem1.DataType).Equals(GetType(String)) Then

    dataItem1.SerializeDataInstance("This is the new cached string value.")
    serverDocument1.Save()
End If

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();
}

Para obter um exemplo de código demonstra como inicializar um cache DataSet em um servidor, consulte Como: Inserir dados em uma pasta de trabalho em um servidor.

Modificando valores nulos em Cache de dados

O cache de dados não armazena os objetos que possuem o valor null quando o documento for salvo e fechado. Essa limitação tem várias conseqüências, quando você modifica dados em cache:

Se você definir qualquer objeto no cache de dados para o valor null, todos os objetos no cache de dados serão automaticamente definidos como null quando o documento é aberto e o cache de dados inteira será limpo quando o documento for salvo e fechado. Ou seja, todos os objetos em cache serão removidos do cache de dados e o CachedData a coleta será vazio.
Se você criar uma solução com null objetos no cache de dados e você deseja inicializar esses objetos usando o ServerDocument classe antes que o documento é aberto pela primeira vez, você deve garantir que você inicializar todos os objetos em cache de dados. Se você inicializar a apenas alguns dos objetos, todos os objetos serão definidos como null quando o documento é aberto e o cache de dados inteira será limpo quando o documento for salvo e fechado.

Acessando os Datasets tipados no Cache

Se você deseja acessar os dados em um dataset tipado a partir de uma solução do Office e a partir de um aplicativo fora do escritório, como, por exemplo, um aplicativo Windows Forms ou um ASP.NET o projeto, você deve definir o dataset tipado em um assembly separado, que é referenciado em ambos os projetos. Se você adicionar o dataset tipado para cada projeto, usando o Data Source Configuration Wizard ou dataset Designer, o.NET Framework tratará os datasets tipados em dois projetos como tipos diferentes. Para obter mais informações sobre como criar datasets tipados, consulte Como: Criar um Dataset tipado.