Acessar dados em documentos no servidor
Você pode programar em relação aos dados em uma personalização em nível de documento sem precisar usar o modelo de objeto do Microsoft Office Word ou Microsoft Office Excel. Isso significa que você pode acessar dados contidos em um documento em um servidor que não tenha o Word ou o Excel instalado. 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 vinculação de dados no assembly da solução vincula os dados personalizados ao documento. Isso é possível porque os dados no documento são separados da interface do usuário. Para obter mais informações, consulte Dados armazenados em cache em personalizações em 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 Recursos disponíveis por aplicativo e tipo de projeto do Office.
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 em tempo de design ou use o CachedAttribute StartCaching 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 cadeia de caracteres XML que é armazenada no documento. Os objetos devem atender a determinados requisitos para serem qualificados para armazenamento em cache. Para obter mais informações, consulte Dados de cache.
O código do lado do servidor pode manipular qualquer objeto de dados no cache de dados. Os controles vinculados a instâncias de dados armazenadas em cache são sincronizados com a interface do usuário, para que todas as alterações feitas no servidor sejam feitas nos dados 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, um aplicativo do Windows Forms ou uma página da Web. O aplicativo que acessa os dados armazenados em cache deve ter confiança total; 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 que são expostas pela CachedData propriedade da ServerDocument classe:
A CachedData propriedade retorna um CachedData, que contém todos os dados armazenados em cache em uma personalização em nível de documento.
Cada CachedData um contém um ou mais CachedDataHostItem objetos. A CachedDataHostItem contém todos os objetos de dados armazenados em cache que são definidos em uma única classe.
Cada CachedDataHostItem um contém um ou mais CachedDataItem objetos. A 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
Sheet1classe de um projeto de pasta de trabalho do Excel. Este exemplo é parte de um exemplo maior que é fornecido para o Save método.
Modificar dados no cache
Para modificar um objeto de dados armazenado em cache, você normalmente executa as seguintes etapas:
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 que representa o CachedDataItem objeto de dados armazenado em cache.
Faça as alterações nesta cópia.
Serialize o objeto alterado de volta 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 DataSetobjetos de conjunto de dados e digitados no cache de DataTabledados. O formato DiffGram garante que as alterações no cache de dados em um documento offline sejam enviadas ao servidor corretamente.
Se desejar executar sua própria serialização para alterações nos dados armazenados em cache, você poderá gravar diretamente na Xml propriedade. Especifique o formato DiffGram se você usar um para atualizar um banco de dados com alterações feitas em dados em um DataSetDataAdapter conjunto de dados , DataTableou digitado. Caso contrário, o atualizará o DataAdapter banco de dados adicionando novas linhas em vez de modificar as linhas existentes.
Modificar dados sem desserializar o valor atual
Em alguns casos, convém 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 tenha um tipo simples, como uma cadeia de caracteres ou inteiro, ou se estiver inicializando um cache DataSet em um documento em um servidor. Nesses casos, você pode usar o método sem primeiro desserializar o SerializeDataInstance 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 é parte de um exemplo maior que é 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 quando você modifica dados armazenados 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 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 ficará vazia.
Se você criar uma solução com objetos nulos no cache de dados e desejar inicializar esses objetos usando a ServerDocument classe antes que o documento seja aberto pela primeira vez, certifique-se de inicializar 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 digitados no cache
Se você deseja acessar os dados em um conjunto de dados tipado de uma solução do Office e de um aplicativo fora do Office, como um aplicativo do Windows Forms ou um projeto ASP.NET, você deve definir o conjunto de dados tipado em um assembly separado que é referenciado em ambos os projetos. Se você adicionar o conjunto de dados tipado a cada projeto usando o Assistente de Configuração de 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.