Exemplarische Vorgehensweise: Binden von Inhaltssteuerelementen an benutzerdefinierte XML-Abschnitte

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 Word 2007 Weitere Informationen 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

Word 2007

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

Diese exemplarische Vorgehensweise veranschaulicht, wie Sie Inhaltssteuerelemente in einer Anpassung auf Dokumentebene für Word 2007 an XML-Daten binden, die in dem Dokument gespeichert sind.

Mit Word 2007 können Sie XML-Daten, die als benutzerdefinierte XML-Abschnitte bezeichnet werden, in einem Dokument speichern. Sie können die Anzeige dieser Daten steuern, indem Sie Inhaltssteuerelemente an Elemente in einem benutzerdefinierten XML-Abschnitt binden. Im Beispieldokument dieser exemplarischen Vorgehensweise werden Mitarbeiterinformationen angezeigt, die in einem benutzerdefinierten XML-Abschnitt gespeichert werden. Wenn Sie das Dokument öffnen, zeigen die Inhaltssteuerelemente die Werte der XML-Elemente an. Am Text in den Inhaltssteuerelementen vorgenommene Änderungen werden im benutzerdefinierten XML-Abschnitt gespeichert.

In dieser exemplarischen Vorgehensweise werden die folgenden Aufgaben veranschaulicht:

Hinzufügen von Inhaltssteuerelementen zum Word-Dokument in einem Projekt auf Dokumentebene zur Entwurfszeit.
Erstellen einer XML-Datendatei und eines XML-Schemas, das die Elemente definiert, die an die Inhaltssteuerelemente gebunden werden sollen.
Anfügen des XML-Schemas an das Dokument zur Entwurfszeit.
Hinzufügen des Inhalts der XML-Datei zu einem benutzerdefinierten XML-Abschnitt im Dokument zur Laufzeit.
Binden der Inhaltssteuerelemente an Elemente im benutzerdefinierten XML-Abschnitt.
Binden eines DropDownListContentControl an eine Gruppe von Werten, die im XML-Schema definiert sind.

Hinweis:
Ihr Computer zeigt möglicherweise für einige der Elemente der Visual Studio-Benutzeroberfläche in der folgenden Anleitung andere Namen oder Standorte an. Diese Elemente sind von der jeweiligen Visual Studio-Version und den verwendeten Einstellungen abhängig. Weitere Informationen finden Sie unter Visual Studio-Einstellungen.

Vorbereitungsmaßnahmen

Zum Durchführen dieser exemplarischen Vorgehensweise benötigen Sie die folgenden Komponenten:

Visual Studio Tools for Office (eine optionale Komponente von Visual Studio 2008 Professional und Visual Studio Team System).
Microsoft Office Word 2007.

Visual Studio Tools for Office wird standardmäßig mit den aufgeführten Versionen von Visual Studio installiert. Wie Sie überprüfen können, ob die Software installiert ist, erfahren Sie in Installieren von Visual Studio Tools for Office.

Erstellen eines neuen Word-Dokumentprojekts

Erstellen Sie ein Word 2007-Dokument, das Sie in der exemplarischen Vorgehensweise verwenden.

So erstellen Sie ein neues Word 2007-Dokumentprojekt

Erstellen Sie ein Word-Dokumentprojekt mit dem Namen EmployeeControls unter Verwendung der Vorlage für ein Word-Dokumentprojekt für 2007 Microsoft Office System. Erstellen Sie ein neues Dokument für die Projektmappe. Weitere Informationen finden Sie unter Gewusst wie: Erstellen von Visual Studio Tools for Office-Projekte.

Visual Studio öffnet das neue Word-Dokument im Designer und fügt dem Projektmappen-Explorer das Projekt EmployeeControls hinzu.

Hinzufügen von Inhaltssteuerelementen zum Dokument

Erstellen Sie eine Tabelle, die drei verschiedene Typen von Inhaltssteuerelementen enthält, in der der Benutzer Informationen über einen Mitarbeiter anzeigen bzw. bearbeiten kann.

So fügen Sie dem Dokument Inhaltssteuerelemente hinzu

Klicken Sie im Word-Dokument, das im Visual Studio-Designer gehostet wird, auf der Multifunktionsleiste auf die Registerkarte Einfügen.
Klicken Sie in der Gruppe Tabellen auf Tabelle, und fügen Sie eine Tabelle mit 2 Spalten und 3 Zeilen ein.
Geben Sie in der ersten Spalte Text ein, sodass sie der folgenden Spalte ähnelt:

Employee Name

Hire Date

Title
Klicken Sie in der zweiten Spalte der Tabelle in die erste Zeile (neben Employee Name).

Klicken Sie in der Multifunktionsleiste auf die Registerkarte Entwickler.

Hinweis:
Wenn die Registerkarte Entwickler nicht sichtbar ist, müssen Sie diese zuerst anzeigen. Weitere Informationen finden Sie unter Gewusst wie: Anzeigen der Registerkarte "Entwickler" auf der Multifunktionsleiste.

Klicken Sie in der Gruppe Steuerelemente auf die Schaltfläche Text, um der ersten Zelle ein PlainTextContentControl hinzuzufügen.
Klicken Sie in der zweiten Spalte der Tabelle in die zweite Zeile (neben Hire Date).
Klicken Sie in der Gruppe Steuerelemente auf die Schaltfläche Datumsauswahl, um der zweiten Zelle ein DatePickerContentControl hinzuzufügen.
Klicken Sie in der zweiten Spalte der Tabelle in die dritte Zeile (neben Title).
Klicken Sie in der Gruppe Steuerelemente auf die Schaltfläche Dropdownliste, um der letzten Zelle ein DropDownListContentControl hinzuzufügen.

Das ist die vollständige Benutzeroberfläche für dieses Projekt. Wenn Sie das Projekt jetzt ausführen, können Sie in der ersten Zeile Text eingeben und in der zweiten Zeile ein Datum auswählen. Im nächsten Schritt fügen Sie die anzuzeigenden Daten in einer XML-Datei an das Dokument an.

Erstellen der XML-Datendatei

Sie erhalten XML-Daten zum Speichern in einem benutzerdefinierten XML-Abschnitt üblicherweise von einer externen Quelle, wie etwa einer Datei oder Datenbank. In dieser exemplarischen Vorgehensweise erstellen Sie eine XML-Datei mit Mitarbeiterdaten, die durch Elemente gekennzeichnet sind, die Sie an die Inhaltssteuerelemente im Dokument binden. Um die Daten zur Laufzeit verfügbar zu machen, betten Sie die XML-Datei als Ressource in die Anpassungsassembly.

So erstellen Sie die Datendatei

Klicken Sie im Menü Projekt auf Neues Element hinzufügen.

Das Dialogfeld Neues Element hinzufügen wird angezeigt.
Wählen Sie im Bereich Vorlagen die Option XML-Datei aus.
Nennen Sie die Datei employees.xml, und klicken Sie dann auf Hinzufügen.

Die Datei employees.xml wird im Code-Editor geöffnet.

Ersetzen Sie den Inhalt der Datei employees.xml durch den folgenden Text:

<?xml version="1.0" encoding="utf-8" ?>
<employees xmlns="https://schemas.microsoft.com/vsto/samples">
  <employee>
    <name>Karina Leal</name>
    <hireDate>1999-04-01</hireDate>
    <title>Manager</title>
  </employee>
</employees>

Klicken Sie im Projektmappen-Explorer auf employees.xml.
Wählen Sie im Eigenschaftenfenster die Build Action-Eigenschaft aus, und ändern Sie dann den Wert in Eingebettete Ressource.

Dieser Schritt bettet die XML-Datei als Ressource in die Assembly ein, wenn Sie das Projekt erstellen. Dadurch können Sie auf den Inhalt der XML-Datei zur Laufzeit zugreifen.

Erstellen eines XML-Schemas

Wenn Sie ein Inhaltssteuerelement an ein einzelnes Element in einem benutzerdefinierten XML-Abschnitt binden möchten, müssen Sie kein XML-Schema verwenden. Um jedoch das DropDownListContentControl an einen Satz von Werten zu binden, müssen Sie ein XML-Schema erstellen, das die zuvor erstellte XML-Datendatei überprüft. Das XML-Schema definiert die möglichen Werte für das title-Element. Im weiteren Verlauf dieser exemplarischen Vorgehensweise binden Sie das DropDownListContentControl an dieses Element.

So erstellen Sie ein XML-Schema

Klicken Sie im Menü Projekt auf Neues Element hinzufügen.

Das Dialogfeld Neues Element hinzufügen wird angezeigt.
Wählen Sie im Bereich Vorlagen die Option XML-Schema aus.
Nennen Sie das Schema employees.xsd, und klicken Sie auf Hinzufügen.

Der Schema-Designer wird geöffnet.
Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf employees.xsd, und klicken Sie dann auf Code anzeigen.

Ersetzen Sie den Inhalt der Datei employees.xsd durch das folgende Schema.

<?xml version="1.0" encoding="utf-8" ?>
<xs:schema xmlns="https://schemas.microsoft.com/vsto/samples" 
    targetNamespace="https://schemas.microsoft.com/vsto/samples"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    elementFormDefault="qualified">
  <xs:element name="employees" type="EmployeesType"></xs:element>
  <xs:complexType name="EmployeesType">
    <xs:all>
      <xs:element name="employee" type="EmployeeType"/>
    </xs:all>
  </xs:complexType>
  <xs:complexType name="EmployeeType">
    <xs:sequence>
      <xs:element name="name" type="xs:string" minOccurs="1" maxOccurs="1"/>
      <xs:element name="hireDate" type="xs:date" minOccurs="1" maxOccurs="1"/>
      <xs:element name="title" type="TitleType" minOccurs="1" maxOccurs="1"/>
    </xs:sequence>
  </xs:complexType>
  <xs:simpleType name="TitleType">
    <xs:restriction base="xs:string">
      <xs:enumeration value ="Engineer"/>
      <xs:enumeration value ="Designer"/>
      <xs:enumeration value ="Manager"/>
    </xs:restriction>
  </xs:simpleType>
</xs:schema>

Klicken Sie im Menü Datei auf Alle speichern, um die Änderungen an den Dateien employees.xml und employees.xsd zu speichern.

Anfügen des XML-Schemas an das Dokument

Sie müssen das XML-Schema an das Dokument anfügen, um das DropDownListContentControl an die gültigen Werte des title-Elements zu binden.

So fügen Sie das XML-Schema an das Dokument an

Aktivieren Sie EmployeeControls.docx im Designer.
Klicken Sie in der Multifunktionsleiste auf die Registerkarte Entwickler.
Klicken Sie in der Gruppe XML auf Schema.
Klicken Sie im Dialogfeld Vorlagen und Add-Ins auf die Registerkarte XML-Schema und dann auf Schema hinzufügen.
Wechseln Sie zum zuvor erstellten Schema employees.xsd, das sich im Projektverzeichnis befindet, und klicken Sie auf Öffnen.
Klicken Sie im Dialogfeld Schemaeinstellungen auf OK.
Klicken Sie auf OK, um das Dialogfeld Vorlagen und Add-Ins zu schließen.

Der Aufgabenbereich XML-Struktur wird geöffnet.
Schließen Sie den XML-Struktur-Aufgabenbereich.

Hinzufügen eines benutzerdefinierten XML-Abschnitts zum Dokument

Bevor Sie die Inhaltssteuerelemente an die Elemente in der XML-Datei binden können, müssen Sie einem neuen benutzerdefiniertem XML-Abschnitt im Dokument den Inhalt der XML-Datei hinzufügen.

So fügen Sie dem Dokument einen benutzerdefinierten XML-Abschnitt hinzu

Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf ThisDocument.cs bzw. ThisDocument.vb, und klicken Sie dann auf Code anzeigen.

Fügen Sie der ThisDocument-Klasse die folgenden Deklarationen hinzu. In diesem Code werden mehrere Objekte deklariert, mit denen Sie dem Dokument einen benutzerdefinierten XML-Abschnitt hinzufügen.

<Cached()> _
Public employeeXMLPartID As String = String.Empty
Private employeeXMLPart As Office.CustomXMLPart
Private Const prefix As String = "xmlns:ns='https://schemas.microsoft.com/vsto/samples'"

[CachedAttribute()]
public string employeeXMLPartID = string.Empty;
private Office.CustomXMLPart employeeXMLPart;
private const string prefix = "xmlns:ns='https://schemas.microsoft.com/vsto/samples'";

Fügen Sie der ThisDocument-Klasse die folgende Methode hinzu. Diese Methode ruft den Inhalt der XML-Datendatei ab, die als Ressource in der Assembly eingebettet ist, und gibt den Inhalt als XML-Zeichenfolge zurück.

Private Function GetXmlFromResource() As String
    Dim asm As System.Reflection.Assembly = _
        System.Reflection.Assembly.GetExecutingAssembly()
    Dim stream1 As System.IO.Stream = asm.GetManifestResourceStream( _
            "EmployeeControls.employees.xml")

    Using resourceReader As System.IO.StreamReader = _
        New System.IO.StreamReader(stream1)
        If resourceReader IsNot Nothing Then
            Return resourceReader.ReadToEnd()
        End If
    End Using

    Return Nothing
End Function

private string GetXmlFromResource()
{
    System.Reflection.Assembly asm =
        System.Reflection.Assembly.GetExecutingAssembly();
    System.IO.Stream stream1 = asm.GetManifestResourceStream(
        "EmployeeControls.employees.xml");

    using (System.IO.StreamReader resourceReader =
            new System.IO.StreamReader(stream1))
    {
        if (resourceReader != null)
        {
            return resourceReader.ReadToEnd();
        }
    }

    return null;
}

Fügen Sie der ThisDocument-Klasse die folgende Methode hinzu. Die AddCustomXmlPart-Methode erstellt einen neuen benutzerdefinierten XML-Abschnitt, der eine XML-Zeichenfolge enthält, die an die Methode übergeben wird.

Um sicherzustellen, dass der benutzerdefinierte XML-Abschnitt nur einmal erstellt wird, erstellt die Methode den benutzerdefinierten XML-Abschnitt nur dann, wenn noch kein benutzerdefinierter XML-Abschnitt mit einer übereinstimmenden GUID im Dokument vorhanden ist. Beim ersten Aufruf dieser Methode wird der Wert der Microsoft.Office.Interop.Word.CustomXMLPart.Id-Eigenschaft in der Zeichenfolge employeeXMLPartID gespeichert. Der Wert der employeeXMLPartID-Zeichenfolge wird im Dokument beibehalten, da er mit dem CachedAttribute-Attribut deklariert wurde.

Private Sub AddCustomXmlPart(ByVal xmlData As String)
    If xmlData IsNot Nothing Then

        employeeXMLPart = Me.CustomXMLParts.SelectByID(employeeXMLPartID)
        If (employeeXMLPart Is Nothing) Then
            employeeXMLPart = Me.CustomXMLParts.Add(xmlData)
            employeeXMLPart.NamespaceManager.AddNamespace("ns", _
                "https://schemas.microsoft.com/vsto/samples")
            employeeXMLPartID = employeeXMLPart.Id
        End If
    End If
End Sub

private void AddCustomXmlPart(string xmlData)
{
    if (xmlData != null)
    {
        employeeXMLPart = this.CustomXMLParts.SelectByID(employeeXMLPartID);
        if (employeeXMLPart == null)
        {
            employeeXMLPart = this.CustomXMLParts.Add(xmlData, missing);
            employeeXMLPart.NamespaceManager.AddNamespace("ns", 
                @"https://schemas.microsoft.com/vsto/samples");
            employeeXMLPartID = employeeXMLPart.Id;
        }
    }
}

Binden der Inhaltssteuerelemente an Elemente im benutzerdefinierten XML-Abschnitt

Binden Sie mit der XMLMapping-Eigenschaft des jeweiligen Inhaltssteuerelements jedes Inhaltssteuerelement an ein Element im benutzerdefinierten XML-Abschnitt.

So binden Sie die Inhaltssteuerelemente an Elemente im benutzerdefinierten XML-Abschnitt

Fügen Sie der ThisDocument-Klasse die folgende Methode hinzu. Mit dieser Methode wird jedes Inhaltssteuerelement an ein Element im benutzerdefinierten XML-Abschnitt gebunden und die Anzeige des Datumsformats für das DatePickerContentControl festgelegt.

Private Sub BindControlsToCustomXmlPart()
    Dim xPathName As String = "ns:employees/ns:employee/ns:name"
    Me.PlainTextContentControl1.XMLMapping.SetMapping(xPathName, _
        prefix, employeeXMLPart)

    Dim xPathDate As String = "ns:employees/ns:employee/ns:hireDate"
    Me.DatePickerContentControl1.DateDisplayFormat = "MMMM d, yyyy"
    Me.DatePickerContentControl1.XMLMapping.SetMapping(xPathDate, _
        prefix, employeeXMLPart)

    Dim xPathTitle As String = "ns:employees/ns:employee/ns:title"
    Me.DropDownListContentControl1.XMLMapping.SetMapping(xPathTitle, _
        prefix, employeeXMLPart)
End Sub

private void BindControlsToCustomXmlPart()
{
    string xPathName = "ns:employees/ns:employee/ns:name";
    this.plainTextContentControl1.XMLMapping.SetMapping(xPathName,
        prefix, employeeXMLPart);

    string xPathDate = "ns:employees/ns:employee/ns:hireDate";
    this.datePickerContentControl1.DateDisplayFormat = "MMMM d, yyyy";
    this.datePickerContentControl1.XMLMapping.SetMapping(xPathDate,
        prefix, employeeXMLPart);

    string xPathTitle = "ns:employees/ns:employee/ns:title";
    this.dropDownListContentControl1.XMLMapping.SetMapping(xPathTitle,
        prefix, employeeXMLPart);
}

Ausführen des Codes beim Öffnen des Dokuments

Erstellen Sie den benutzerdefinierten XML-Abschnitt, und binden Sie die benutzerdefinierten Steuerelemente an die Daten, wenn das Dokument geöffnet wird.

So führen Sie den Code beim Öffnen des Dokuments aus

Fügen Sie der ThisDocument_Startup-Methode der ThisDocument-Klasse den folgenden Code hinzu. Mit diesem Code wird die XML-Zeichenfolge aus der Datei employees.xml abgerufen, die XML-Zeichenfolge einem neuen benutzerdefinierten XML-Abschnitt im Dokument hinzugefügt, und die Inhaltssteuerelemente werden an Elemente im benutzerdefinierten XML-Abschnitt gebunden.
```
Dim xmlData As String = GetXmlFromResource()
If xmlData IsNot Nothing Then
    AddCustomXmlPart(xmlData)
    BindControlsToCustomXmlPart()
End If
```
```
string xmlData = GetXmlFromResource();

if (xmlData != null)
{
    AddCustomXmlPart(xmlData);
    BindControlsToCustomXmlPart();
}
```

Testen des Projekts

Wenn Sie das Dokument öffnen, zeigen die Inhaltssteuerelemente Daten der Elemente im benutzerdefinierten XML-Abschnitt an. Sie können auf das DropDownListContentControl klicken, um einen von drei gültigen Werten, die in der Datei employees.xsd definiert werden, für das title-Element auszuwählen. Wenn Sie die Daten in einem Inhaltssteuerelement bearbeiten, werden die neuen Werte im benutzerdefinierten XML-Abschnitt im Dokument gespeichert.

So testen Sie die Inhaltssteuerelemente

Drücken Sie F5, um das Projekt auszuführen.
Überprüfen Sie, ob die Tabelle im Dokument ähnlich aussieht wie die folgende Tabelle. Jede der Zeichenfolgen in der zweiten Spalte wird von einem Element im benutzerdefinierten XML-Abschnitt im Dokument abgerufen.

Employee Name

Karina Leal

Hire Date

April 1, 1999

Title

Manager
Klicken Sie in die Zelle rechts neben der Zelle Employee Name, und geben Sie einen anderen Namen ein.
Klicken Sie in die Zelle rechts neben der Zelle Hire Date, und wählen Sie in der Datumsauswahl ein anderes Datum aus.
Klicken Sie in die Zelle rechts neben der Zelle Title, und wählen Sie ein neues Element aus der Dropdownliste aus.
Speichern und schließen Sie das Dokument.
Öffnen Sie in Windows Explorer den Ordner \bin\Debug unter dem Speicherort des Projekts.
Klicken Sie mit der rechten Maustaste auf EmployeeControls.docx, und klicken Sie dann auf Umbenennen.
Nennen Sie die Datei EmployeeControls.docx.zip.

Das Dokument EmployeeControls.docx wird im Open XML-Format gespeichert. Durch Umbenennen dieses Dokuments mit der ZIP-Dateinamenserweiterung können Sie den Inhalt des Dokuments überprüfen. Weitere Informationen über Open XML finden Sie im technischen Artikel Einführung in die Open XML-Dateiformate.
Doppelklicken Sie auf die Datei EmployeeControls.docx.zip.
Doppelklicken Sie auf den Ordner customXml.
Klicken Sie mit der rechten Maustaste auf item2.xml, und klicken Sie dann auf Öffnen.

Diese Datei enthält den benutzerdefinierten XML-Abschnitt, den Sie dem Dokument hinzugefügt haben.
Überprüfen Sie, ob die Elemente name, hireDate und title die neuen Werte enthalten, die Sie in die Inhaltssteuerelemente im Dokument eingegeben haben.
Schließen Sie die Datei item2.xml.

Nächste Schritte

Weitere Informationen über die Verwendung von Inhaltssteuerelementen finden Sie in den folgenden Themen:

Erstellen Sie eine Vorlage mithilfe aller verfügbaren Inhaltssteuerelemente. Weitere Informationen finden Sie unter Exemplarische Vorgehensweise: Erstellen einer Vorlage mithilfe von Inhaltssteuerelementen.
Ändern Sie die Daten in den benutzerdefinierten XML-Abschnitten bei geschlossenem Dokument. Wenn der Benutzer das Dokument das nächste Mal öffnet, zeigen die Inhaltssteuerelemente, die an die XML-Elemente gebunden sind, die neuen Daten an. Weitere Informationen finden Sie unter Gewusst wie: Hinzufügen von benutzerdefinierten XML-Abschnitten zu Dokumenten, ohne Microsoft Office zu starten.
Schützen Sie Teile eines Dokuments mithilfe von Inhaltssteuerelementen. Weitere Informationen finden Sie unter Gewusst wie: Schützen von Teilen von Dokumenten mithilfe von Inhaltssteuerelementen.

Siehe auch

Freigeben über