Acceso a datos de documentos en el servidor

Artículo
04/28/2010

Actualización: noviembre 2007

Se aplica a
La información de este tema sólo se aplica a los proyectos de Visual Studio Tools para Office y versiones de Microsoft Office especificados. Tipo de proyecto Proyectos de nivel de documento Versión de Microsoft Office Microsoft Office System 2007 Microsoft Office 2003 Para obtener más información, vea Características disponibles por aplicación y tipo de proyecto.

La información de este tema sólo se aplica a los proyectos de Visual Studio Tools para Office y versiones de Microsoft Office especificados.

Tipo de proyecto

Proyectos de nivel de documento

Versión de Microsoft Office

Microsoft Office System 2007
Microsoft Office 2003

Para obtener más información, vea Características disponibles por aplicación y tipo de proyecto.

Visual Studio Tools para Office permite programar basándose en los datos de un documento sin tener que utilizar el modelo de objetos de Microsoft Office Word o Microsoft Office Excel. Esto significa que puede tener acceso a los datos contenidos en un documento en un servidor que no tenga Word ni Excel instalados. Por ejemplo, el código de un servidor (como en una página de ASP.NET) puede personalizar los datos de un documento y enviar el documento personalizado a un usuario final. Cuando el usuario final abre el documento, el código de enlace de datos del ensamblado de la solución enlaza los datos personalizados del documento. Esto es posible porque los datos del documento están separados de la interfaz de usuario. Para obtener más información, vea Modelo de datos en las personalizaciones de nivel de documento.

Almacenar en memoria caché los datos para su uso en un servidor

Para almacenar en memoria caché un objeto de datos de un documento, márquelo en tiempo de diseño con el atributo CachedAttribute o utilice en tiempo de ejecución el método StartCaching de un elemento host. Cuando se almacena en la memoria caché un objeto de datos en un documento, el tiempo de ejecución de Visual Studio Tools para Office serializa el objeto en una cadena XML que se almacena en el documento. Los objetos deben cumplir determinados requisitos para que puedan almacenarse en memoria caché. Para obtener más información, vea Almacenar datos en caché.

El código del servidor puede manipular cualquier objeto de datos en la caché de datos. Los controles que están enlazados a instancias de datos almacenadas en memoria caché se sincronizan con la interfaz de usuario, de manera que los cambios del lado del servidor realizados en los datos se mostrarán automáticamente cuando el documento se abra en el cliente.

Tener acceso a los datos de la memoria caché

Es posible tener acceso a los datos contenidos en la memoria caché de aplicaciones ajenas a Office, por ejemplo, desde una aplicación de consola, una aplicación de formularios Windows Forms o una página Web. La aplicación que tiene acceso a los datos almacenados en memoria caché debe tener plena confianza; una aplicación Web que sólo tenga confianza parcial no puede insertar, recuperar ni cambiar los datos almacenados en la memoria caché de un documento de Office.

Se puede obtener acceso a la caché de datos a través de una jerarquía de colecciones ofrecida por la propiedad CachedData de la clase ServerDocument:

La propiedad CachedData devuelve Microsoft.VisualStudio.Tools.Applications.CachedData, que contiene todos los datos almacenados en memoria caché en una personalización de nivel de documento.
Cada Microsoft.VisualStudio.Tools.Applications.CachedData contiene uno o más objetos CachedDataHostItem. CachedDataHostItem contiene todos los objetos de datos almacenados en memoria caché que se definen dentro de una clase única.
Cada CachedDataHostItem contiene uno o más objetos CachedDataItem. CachedDataItem representa un único objeto de datos almacenado en la memoria caché.

En el ejemplo de código siguiente se muestra cómo tener acceso a una cadena almacenada en memoria caché en la clase Sheet1 de un proyecto de libro de Excel. Este ejemplo forma parte de un ejemplo más extenso proporcionado para el método ServerDocument.Save.

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 obtener un ejemplo de código que muestra cómo tener acceso a los datos en un objeto DataSet almacenado en caché, vea Cómo: Recuperar los datos almacenados en la memoria caché de un libro ubicado en un servidor.

Nota:
La clase ServerDocument y las clases de datos almacenados en memoria caché en el espacio de nombres Microsoft.VisualStudio.Tools.Applications sólo se pueden utilizar con soluciones de Microsoft Office System 2007. Si está trabajando con soluciones para Microsoft Office 2003, use la clase ServerDocument y las clases de datos almacenados en memoria caché en el espacio de nombres Microsoft.VisualStudio.Tools.Applications.Runtime. Para obtener más información, vea Administrar documentos en un servidor mediante la clase ServerDocument.

La clase ServerDocument y las clases de datos almacenados en memoria caché en el espacio de nombres Microsoft.VisualStudio.Tools.Applications sólo se pueden utilizar con soluciones de Microsoft Office System 2007. Si está trabajando con soluciones para Microsoft Office 2003, use la clase ServerDocument y las clases de datos almacenados en memoria caché en el espacio de nombres Microsoft.VisualStudio.Tools.Applications.Runtime. Para obtener más información, vea Administrar documentos en un servidor mediante la clase ServerDocument.

Modificar datos en la caché

Para modificar un objeto de datos almacenado en la memoria caché, normalmente se siguen estos pasos:

Deserialice la representación XML del objeto en caché en una nueva instancia del objeto. Puede tener acceso al código XML utilizando la propiedad Xml de CachedDataItem que representa el objeto de datos almacenado en memoria caché.
Realice los cambios en esta copia.
Serialice de nuevo el objeto modificado en la caché de datos utilizando una de las opciones siguientes:
- Si desea serializar automáticamente los cambios, utilice el método SerializeDataInstance. Este método utiliza el formato DiffGram para serializar objetos de DataSet, de DataTable y de conjuntos de datos con tipo en la caché de datos. El formato DiffGram garantiza que los cambios en la caché de datos de un documento sin conexión se envían correctamente al servidor. Para obtener más información, vea DiffGrams (ADO.NET).
- Si desea realizar su propia serialización para llevar a cabo cambios en los datos almacenados en memoria caché, puede escribir directamente en la propiedad Xml. Especifique el formato DiffGram si utiliza un DataAdapter para actualizar una base de datos con los cambios efectuados en datos en un DataSet, DataTable o un conjunto de datos con tipo. De lo contrario, el DataAdapter actualizará la base de datos agregando nuevas filas en lugar de modificar las filas existentes.

Para obtener un ejemplo de código que muestre cómo serializar los cambios en un objeto de datos almacenado en memoria caché escribiendo directamente en la propiedad Xml, vea Cómo: Cambiar los datos almacenados en caché en un libro ubicado en un servidor.

Modificar datos sin deserializar el valor actual

En algunos casos, puede ser conveniente modificar el valor del objeto en caché sin deserializar antes su valor actual. Por ejemplo, puede hacerlo para modificar el valor de un objeto que tiene un tipo simple, como una cadena o un entero, o inicializar un DataSet almacenado en memoria caché en un documento de un servidor. En estos casos, puede utilizar el método SerializeDataInstance sin deserializar primero el valor actual del objeto en caché.

En el ejemplo de código siguiente se muestra cómo cambiar el valor de una cadena almacenada en memoria caché en la clase Sheet1 de un proyecto de libro de Excel. Este ejemplo forma parte de un ejemplo más extenso proporcionado para el método ServerDocument.Save.

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 obtener un ejemplo de código que muestra cómo inicializar un objeto DataSet almacenado en memoria caché en un servidor, vea Cómo: Insertar datos en un libro ubicado en un servidor.

Modificar los valores Null en la caché de datos

La caché de datos no almacena objetos cuyo valor es null al guardar y cerrar el documento. Esta limitación tiene varias consecuencias al modificar los datos almacenados en memoria caché:

Si establece cualquier objeto de la caché de datos en el valor null, todos los objetos de la caché de datos se establecerán automáticamente en null al abrir el documento, y la caché de datos completa se borrará al guardar y cerrar el documento. Es decir, todos los objetos en caché se quitarán de la caché de datos y la colección CachedData quedará vacía.
Si genera una solución con objetos null en la caché de datos y desea inicializar estos objetos utilizando la clase ServerDocument antes de abrir el documento por primera vez, debe asegurarse de inicializar todos los objetos en la caché de datos. Si sólo inicializa algunos de ellos, todos se establecerán en null al abrir el documento, y la caché de datos completa se borrará al guardar y cerrar el documento.

Tener acceso a conjuntos de datos con tipo en la caché

Si desea tener acceso a los datos de un conjunto de datos con tipo desde una solución de Visual Studio Tools para Office y desde una aplicación ajena a Office, como una aplicación de formularios Windows Forms o un proyecto de ASP.NET, tenga en cuenta las siguientes consideraciones:

Es necesario definir el conjunto de datos con tipo en un ensamblado independiente de aquel al que se hace referencia en ambos proyectos. Si agrega el conjunto de datos con tipo a cada proyecto mediante el Asistente para la configuración de orígenes de datos o el Diseñador de DataSet, .NET Framework tratará los conjuntos de datos con tipo que aparecen en los dos proyectos como tipos diferentes. Para obtener más información sobre cómo crear conjuntos de datos con tipo, vea Cómo: Crear un conjunto de datos con tipo.
Debe conceder al ensamblado que contiene el conjunto de datos con tipo la confianza adecuada en la directiva de seguridad de cada usuario final. Para obtener más información, vea Requisitos de seguridad para ejecutar las soluciones de Office (2003 System).