Zugreifen auf Daten in Dokumenten auf dem Server

Artikel
08/10/2011

Sie können beim Programmieren die Daten einer Anpassung auf Dokumentebene verwenden, ohne dass Sie das Objektmodell von Microsoft Office Word oder Microsoft Office Excel verwenden müssen. Das bedeutet, dass Sie auf Daten zugreifen können, die in einem Dokument auf einem Server enthalten sind, auf dem Word oder Excel nicht installiert sind. Beispielsweise können mithilfe von Code auf dem Server (z. B. auf einer ASP.NET-Seite) die Daten in einem Dokument angepasst werden, und das angepasste Dokument kann an einen Endbenutzer gesendet werden. Wenn der Endbenutzer das Dokument öffnet, bindet der Code für die Datenbindung in der Projektmappenassembly die angepassten Daten in das Dokument. Dies ist möglich, da die Daten in dem Dokument von der Benutzeroberfläche getrennt sind. Weitere Informationen hierzu finden Sie unter Zwischengespeicherte Daten in Anpassungen auf Dokumentebene.

Betrifft: Die Informationen in diesem Thema betreffen Projekte auf Dokumentebene für die folgenden Anwendungen: Excel 2007 und Excel 2010, Word 2007 und Word 2010. Weitere Informationen finden Sie unter Verfügbare Funktionen nach Office-Anwendung und Projekttyp.

Zwischenspeichern von Daten für die Verwendung auf einem Server

Sie können ein Datenobjekt in einem Dokument zwischenspeichern, indem Sie es zur Entwurfszeit mit dem CachedAttribute-Attribut markieren oder zur Laufzeit die StartCaching-Methode eines Hostelements verwenden. Wenn Sie ein Datenobjekt in einem Dokument zwischenspeichern, serialisiert Visual Studio Tools for Office-Laufzeit das Objekt in eine XML-Zeichenfolge, die im Dokument gespeichert wird. Objekte müssen bestimmte Anforderungen erfüllen, um für das Zwischenspeichern geeignet zu sein. Weitere Informationen hierzu finden Sie unter Zwischenspeichern von Daten.

In serverseitigem Code können alle Datenobjekte im Datencache bearbeitet werden. Steuerelemente, die an zwischengespeicherte Dateninstanzen gebunden sind, werden mit der Benutzeroberfläche synchronisiert, sodass alle serverseitigen Änderungen der Daten automatisch beim Öffnen des Dokuments auf dem Client angezeigt werden.

Zugreifen auf Daten im Cache

Sie können von Anwendungen außerhalb von Office, z. B. von einer Konsolenanwendung, einer Windows Forms-Anwendung oder einer Webseite, auf Daten im Cache zugreifen. Die Anwendung, die auf die zwischengespeicherten Daten zugreift, muss als vollständig vertrauenswürdig eingestuft sein. Eine nur teilweise vertrauenswürdige Webanwendung kann Daten, die in einem Office-Dokument zwischengespeichert sind, nicht einfügen, abrufen oder ändern.

Auf den Datencache kann mithilfe einer Auflistungshierarchie zugegriffen werden, die durch die CachedData-Eigenschaft der ServerDocument-Klasse verfügbar gemacht wird:

Die CachedData-Eigenschaft gibt Microsoft.VisualStudio.Tools.Applications.CachedData mit allen zwischengespeicherten Daten in einer Anpassung auf Dokumentebene zurück.
Jedes Microsoft.VisualStudio.Tools.Applications.CachedData enthält mindestens ein CachedDataHostItem-Objekt. Ein CachedDataHostItem enthält sämtliche zwischengespeicherten Datenobjekte, die innerhalb einer einzelnen Klasse definiert sind.
Jedes CachedDataHostItem enthält mindestens ein CachedDataItem-Objekt. Ein CachedDataItem stellt ein einzelnes zwischengespeichertes Datenobjekt dar.

Das folgende Codebeispiel veranschaulicht, wie Sie auf eine Zeichenfolge im Cache in der Sheet1-Klasse eines Excel-Arbeitsmappenprojekts zugreifen können. Dieses Beispiel ist Teil eines umfangreicheren Beispiels für die ServerDocument.Save-Methode.

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"];

Ein Codebeispiel, das veranschaulicht, wie Sie auf die Daten in einem DataSet im Cache zugreifen, finden Sie unter Gewusst wie: Abrufen von zwischengespeicherten Daten aus einer Arbeitsmappe auf einem Server.

Ändern von Daten im Cache

Um ein Datenobjekt im Cache zu ändern, führen Sie normalerweise die folgenden Schritte aus:

Deserialisieren Sie die XML-Darstellung des zwischengespeicherten Objekts in eine neue Instanz des Objekts. Sie können über die Xml-Eigenschaft des CachedDataItem, das das zwischengespeicherte Datenobjekt darstellt, auf die XML-Darstellung zugreifen.
Nehmen Sie die Änderungen an dieser Kopie vor.
Serialisieren Sie mithilfe einer der folgenden Optionen das bearbeitete Objekt wieder in den Datencache:
- Wenn Sie die Änderungen automatisch serialisieren möchten, verwenden Sie die SerializeDataInstance-Methode. Diese Methode verwendet das DiffGram-Format, um DataSet, DataTable und typisierte DataSet-Objekte in den Datencache zu serialisieren. Durch das DiffGram-Format wird sichergestellt, dass Änderungen am Datencache in einem Offlinedokument korrekt an den Server gesendet werden. Weitere Informationen hierzu finden Sie unter DiffGrams (ADO.NET).
- Wenn Sie eine eigene Serialisierung für Änderungen an zwischengespeicherten Daten durchführen möchten, können Sie direkt in die Xml-Eigenschaft schreiben. Geben Sie das DiffGram-Format an, wenn Sie einen DataAdapter verwenden, um eine Datenbank mit Änderungen zu aktualisieren, die an Daten in einem DataSet, einer DataTable oder einem typisierten DataSet vorgenommen wurden. Andernfalls aktualisiert der DataAdapter die Datenbank, indem neue Zeilen hinzugefügt werden, statt vorhandene Zeilen zu ändern.

Ein Codebeispiel für das Serialisieren von Änderungen an einem zwischengespeicherten Datenobjekt durch direktes Schreiben in die Xml-Eigenschaft finden Sie unter Gewusst wie: Ändern zwischengespeicherter Daten in einer Arbeitsmappe auf einem Server.

Ändern von Daten ohne Deserialisieren des aktuellen Werts

In einigen Fällen ist es zweckmäßig, den Wert des zwischengespeicherten Objekts zu ändern, ohne zuvor den aktuellen Wert zu deserialisieren. Dies kann sinnvoll sein, wenn Sie den Wert eines Objekt ändern, das einem einfachen Typ angehört, z. B. eine Zeichenfolge oder eine Ganzzahl, oder wenn Sie ein zwischengespeichertes DataSet in einem Dokument auf einem Server initialisieren. In diesen Fällen können Sie die SerializeDataInstance-Methode verwenden, ohne zuerst den aktuellen Wert des zwischengespeicherten Objekts zu deserialisieren.

Das folgende Codebeispiel veranschaulicht, wie Sie den Wert einer Zeichenfolge im Cache in der Sheet1-Klasse eines Excel-Arbeitsmappenprojekts ändern können. Dieses Beispiel ist Teil eines umfangreicheren Beispiels für die ServerDocument.Save-Methode.

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

Ein Codebeispiel, das veranschaulicht, wie Sie ein zwischengespeichertes DataSet auf einem Server initialisieren, finden Sie unter Gewusst wie: Einfügen von Daten in eine Arbeitsmappe auf einem Server.

Ändern von NULL-Werten im Datencache

Im Datencache werden keine Objekte gespeichert, die beim Speichern und Schließen des Dokuments den Wert null haben. Diese Einschränkung hat mehrere Folgen, wenn Sie zwischengespeicherte Daten ändern:

Wenn Sie für ein Objekt im Datencache den Wert null festlegen, wird für alle Objekte im Datencache beim Öffnen des Dokuments automatisch der Wert null festgelegt, und der gesamte Datencache wird geleert, wenn das Dokument gespeichert und geschlossen wird. Das bedeutet, dass alle zwischengespeicherten Objekte aus dem Datencache entfernt werden und die CachedData-Auflistung leer ist.
Wenn Sie eine Projektmappe mit null-Objekten im Datencache erstellen und diese Objekte mithilfe der ServerDocument-Klasse initialisieren möchten, bevor das Dokument das erste Mal geöffnet wird, müssen Sie sicherstellen, dass Sie alle Objekte im Datencache initialisieren. Wenn Sie nur einige der Objekte initialisieren, wird für alle Objekte im Datencache beim Öffnen des Dokuments der Wert null festgelegt, und der gesamte Datencache wird geleert, wenn das Dokument gespeichert und geschlossen wird.

Zugreifen auf typisierte DataSets im Cache

Wenn Sie auf die Daten in einem typisierten DataSet sowohl aus einer Office-Lösung als auch einer Anwendung außerhalb von Office, z. B. einer Windows Forms-Anwendung oder einem ASP.NET-Projekt, zugreifen möchten, müssen Sie das typisierte DataSet in einer separaten Assembly definieren, auf die in beiden Projekten verwiesen wird. Wenn Sie beiden Projekten das typisierte DataSet mithilfe des Assistenten zum Konfigurieren von Datenquellen oder des DataSet-Designers hinzufügen, behandelt .NET Framework die typisierten DataSets in beiden Projekten als unterschiedliche Typen. Weitere Informationen über das Erstellen von typisierten DataSets finden Sie unter Gewusst wie: Erstellen eines typisierten Datasets.