Zugreifen auf Daten in Dokumenten auf dem Server

Artikel
04/28/2010

Aktualisiert: November 2007

Betrifft
Die Informationen in diesem Thema gelten nur für die angegebenen Projekte und Versionen von Visual Studio Tools for Office von Microsoft Office. Projekttyp Projekte auf Dokumentebene Microsoft Office-Version 2007 Microsoft Office System Microsoft Office 2003 Weitere Informationen hierzu finden Sie unter Verfügbare Features nach Anwendung und Projekttyp.

Die Informationen in diesem Thema gelten nur für die angegebenen Projekte und Versionen von Visual Studio Tools for Office von Microsoft Office.

Projekttyp

Projekte auf Dokumentebene

Microsoft Office-Version

2007 Microsoft Office System
Microsoft Office 2003

Weitere Informationen hierzu finden Sie unter Verfügbare Features nach Anwendung und Projekttyp.

Mit Visual Studio Tools for Office können Sie 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 Datenmodell in Anpassungen auf Dokumentebene.

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 die 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.

Hinweis:
Die ServerDocument-Klasse und die zwischengespeicherten Datenklassen im Microsoft.VisualStudio.Tools.Applications-Namespace können nur mit Projektmappen für 2007 Microsoft Office System verwendet werden. Wenn Sie mit Projektmappen für Microsoft Office 2003 arbeiten, verwenden Sie die ServerDocument-Klasse und zwischengespeicherte Datenklassen im Microsoft.VisualStudio.Tools.Applications.Runtime-Namespace. Weitere Informationen hierzu finden Sie unter Verwalten von Dokumenten auf einem Server mit der ServerDocument-Klasse.

Die ServerDocument-Klasse und die zwischengespeicherten Datenklassen im Microsoft.VisualStudio.Tools.Applications-Namespace können nur mit Projektmappen für 2007 Microsoft Office System verwendet werden. Wenn Sie mit Projektmappen für Microsoft Office 2003 arbeiten, verwenden Sie die ServerDocument-Klasse und zwischengespeicherte Datenklassen im Microsoft.VisualStudio.Tools.Applications.Runtime-Namespace. Weitere Informationen hierzu finden Sie unter Verwalten von Dokumenten auf einem Server mit der ServerDocument-Klasse.

Ä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

Beachten Sie Folgendes, wenn Sie auf Daten in einem typisierten DataSet mithilfe einer Visual Studio Tools for Office-Projektmappe bzw. einer nicht zu Office gehörenden Anwendung (z. B. eine Windows Forms-Anwendung oder ein ASP.NET-Projekt) zugreifen möchten:

Sie müssen 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.
Sie müssen der Assembly, die das typisierte DataSet enthält, in der Sicherheitsrichtlinie jedes Endbenutzers eine entsprechende Vertrauenswürdigkeit gewähren. Weitere Informationen hierzu finden Sie unter Sicherheitsanforderungen für die Ausführung von Office-Projektmappen (2003 System).