Exemplarische Vorgehensweise: Binden von Inhaltssteuerelementen an benutzerdefinierte XML-Komponenten

Artikel
10/10/2023

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

Gilt für: Die Informationen in diesem Thema gelten für Projekte auf Dokumentebene für Word. Weitere Informationen finden Sie unter features available by Office-App lication and project type.

Word ermöglicht es Ihnen, XML-Daten, benannte benutzerdefinierte XML-Teile, in einem Dokument zu 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 einer benutzerdefinierten XML-Komponente 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

Auf Ihrem Computer werden möglicherweise andere Namen oder Speicherorte für die Benutzeroberflächenelemente von Visual Studio angezeigt als die in den folgenden Anweisungen aufgeführten. Diese Elemente sind von der jeweiligen Visual Studio-Version und den verwendeten Einstellungen abhängig. Weitere Informationen finden Sie unter Personalisieren der IDE.

Voraussetzungen

Zum Abschließen dieser exemplarischen Vorgehensweise benötigen Sie Folgendes:

Eine Edition von Visual Studio, die die Microsoft Office-Entwicklungstools umfasst. Weitere Informationen finden Sie unter Konfigurieren eines Computers zum Entwickeln von Office-Lösungen.
Microsoft Word.

Erstellen eines neuen Word-Dokumentprojekts

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

So erstellen Sie ein neues Word-Dokumentprojekt

Erstellen Sie ein Word-Dokumentprojekt mit dem Namen EmployeeControls. Erstellen Sie ein neues Dokument für die Projektmappe. Weitere Informationen finden Sie unter How to: Create Office projects in Visual Studio.

Visual Studio öffnet das neue Word-Dokument im Designer und fügt das EmployeeControls-Projekt zu Projektmappen-Explorer 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

Wählen Sie im Word-Dokument, das im Visual Studio-Designer gehostet wird, im Menüband die Registerkarte "Einfügen " aus.
Wählen Sie in der Gruppe "Tabellen " die Option "Tabelle" aus, 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:

Mitarbeitername

Einstellungsdatum

Titel
Wählen Sie in der zweiten Spalte der Tabelle die erste Zeile (neben "Mitarbeitername") aus.
Wählen Sie im Menüband die Registerkarte "Entwicklertools " aus.

Hinweis

Wenn die Registerkarte Entwickler nicht sichtbar ist, müssen Sie diese zuerst anzeigen. Weitere Informationen finden Sie unter How to: Show the developer tab on the ribbon.
Wählen Sie in der Gruppe "Steuerelemente " die Schaltfläche "Text " aus, um der ersten Zelle einen PlainTextContentControl Text hinzuzufügen.
Wählen Sie in der zweiten Spalte der Tabelle die zweite Zeile (neben Einstellungsdatum) aus.
Wählen Sie in der Gruppe "Steuerelemente" die Schaltfläche "Datumsauswahl" aus, um der zweiten Zelle einen DatePickerContentControl Eintrag hinzuzufügen.
Wählen Sie in der zweiten Spalte der Tabelle die dritte Zeile (neben "Titel") aus.
Wählen Sie in der Gruppe "Steuerelemente" die Dropdownliste aus, um der letzten Zelle einen DropDownListContentControl Eintrag 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.


Mitarbeitername
Einstellungsdatum
Titel

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

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.
Benennen Sie die Datei employees.xml, und wählen Sie dann die Schaltfläche "Hinzufügen" aus.

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="http://schemas.microsoft.com/vsto/samples">
  <employee>
    <name>Karina Leal</name>
    <hireDate>1999-04-01</hireDate>
    <title>Manager</title>
  </employee>
</employees>

Wählen Sie in Projektmappen-Explorer die Datei "employees.xml" aus.
Wählen Sie im Eigenschaftenfenster die Eigenschaft "Buildaktion" 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 zur Laufzeit auf den Inhalt der XML-Datei 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" das XML-Schema aus.
Benennen Sie das Schema employees.xsd , und wählen Sie die Schaltfläche "Hinzufügen " aus.

Der Schema-Designer wird geöffnet.
Öffnen Sie in Projektmappen-Explorer das Kontextmenü für employees.xsd, und wählen Sie dann "Code anzeigen" aus.

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

<?xml version="1.0" encoding="utf-8" ?>
<xs:schema xmlns="http://schemas.microsoft.com/vsto/samples"
    targetNamespace="http://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 Ihre Änderungen in 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 ( Word 2013 )

Aktivieren Sie EmployeeControls.docx im Designer.
Wählen Sie im Menüband die Registerkarte "Entwicklertools " und dann die Schaltfläche "Add-Ins " aus.
Wählen Sie im Dialogfeld "Vorlagen und Add-Ins " die Registerkarte "XML-Schema " und dann die Schaltfläche "Schema hinzufügen" aus.
Navigieren Sie zu dem zuvor erstellten "employees.xsd "-Schema, das sich in Ihrem Projektverzeichnis befindet, und wählen Sie dann die Schaltfläche "Öffnen " aus.
Klicken Sie im Dialogfeld "Schema Einstellungen" auf die Schaltfläche "OK".
Klicken Sie auf die Schaltfläche 'OK ', um das Dialogfeld 'Vorlagen und Add-Ins' zu schließen.

So fügen Sie das XML-Schema an das Dokument an (Word 2010)

Aktivieren Sie EmployeeControls.docx im Designer.
Wählen Sie im Menüband die Registerkarte "Entwicklertools " aus.
Wählen Sie in der XML-Gruppe die Schaltfläche "Schema " aus.
Wählen Sie im Dialogfeld "Vorlagen und Add-Ins " die Registerkarte "XML-Schema " und dann die Schaltfläche "Schema hinzufügen" aus.
Navigieren Sie zu dem zuvor erstellten "employees.xsd "-Schema, das sich in Ihrem Projektverzeichnis befindet, und wählen Sie die Schaltfläche "Öffnen " aus.
Klicken Sie im Dialogfeld "Schema Einstellungen" auf die Schaltfläche "OK".
Klicken Sie auf die Schaltfläche 'OK ', um das Dialogfeld 'Vorlagen und Add-Ins' zu schließen.

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

Hinzufügen eines benutzerdefinierten XML-Webparts 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

Öffnen Sie in Projektmappen-Explorer das Kontextmenü für ThisDocument.cs oder ThisDocument.vb, und wählen Sie dann "Code anzeigen" aus.

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.

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

<Cached()> _
Public employeeXMLPartID As String = String.Empty
Private employeeXMLPart As Office.CustomXMLPart
Private Const prefix As String = "xmlns:ns='http://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 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;
}

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

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 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 void AddCustomXmlPart(string xmlData)
{
    if (xmlData != null)
    {
        employeeXMLPart = this.CustomXMLParts.SelectByID(employeeXMLPartID);
        if (employeeXMLPart == null)
        {
            employeeXMLPart = this.CustomXMLParts.Add(xmlData);
            employeeXMLPart.NamespaceManager.AddNamespace("ns", 
                @"http://schemas.microsoft.com/vsto/samples");
            employeeXMLPartID = employeeXMLPart.Id;
        }
    }
}

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", _
                "http://schemas.microsoft.com/vsto/samples")
            employeeXMLPartID = employeeXMLPart.Id
        End If
    End If
End Sub

Binden der Inhaltssteuerelemente an Elemente im benutzerdefinierten XML-Teil

Binden Sie jedes Inhaltssteuerelement an ein Element im benutzerdefinierten XML-Teil, indem Sie die XMLMapping-Eigenschaft jedes Inhaltssteuerelements verwenden.

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

Füge 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 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);
}

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

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. Dieser Code ruft die XML-Zeichenfolge aus der Datei employees.xml ab, fügt die XML-Zeichenfolge zu einem neuen benutzerdefinierten XML-Teil im Dokument hinzu und bindet die Inhaltssteuerelemente an Elemente im benutzerdefinierten XML-Teil.
- C#
- VB
```
string xmlData = GetXmlFromResource();

if (xmlData != null)
{
    AddCustomXmlPart(xmlData);
    BindControlsToCustomXmlPart();
}
```
```
Dim xmlData As String = GetXmlFromResource()
If xmlData IsNot Nothing Then
    AddCustomXmlPart(xmlData)
    BindControlsToCustomXmlPart()
End If
```

Testen des Projekts

Wenn Sie das Dokument öffnen, zeigen die Inhaltssteuerelemente Daten der Elemente im benutzerdefinierten XML-Abschnitt an. Sie können auf die DropDownListContentControl Option klicken, um einen von drei gültigen Werten für das title Element auszuwählen, die in der Datei employees.xsd definiert sind. 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.

Spalte Wert

Mitarbeitername Karina Leal

Einstellungsdatum 1. April 1999

Titel Vorgesetzter
Wählen Sie die Zelle rechts neben der Zelle "Mitarbeitername " aus, und geben Sie einen anderen Namen ein.
Wählen Sie die Zelle rechts neben der Zelle "Einstellungsdatum " aus, und wählen Sie in der Datumsauswahl ein anderes Datum aus.
Wählen Sie die Zelle rechts neben der Zelle "Titel " aus, und wählen Sie ein neues Element aus der Dropdownliste aus.
Speichern und schließen Sie das Dokument.
Öffnen Sie in Explorer den Ordner \bin\Debug unter dem Speicherort Ihres Projekts.
Öffnen Sie das Kontextmenü für EmployeeControls.docx, und wählen Sie dann "Umbenennen" aus.
Nennen Sie die Datei EmployeeControls.docx.zip.

Das Document EmployeeControls.docx wird im Open XML-Format gespeichert. Indem Sie dieses Dokument mit der Dateinamenerweiterung ZIP umbenennen, können Sie den Inhalt des Dokuments untersuchen. Weitere Informationen zu Open XML finden Sie im technischen Artikel Einführung in die Open XML-Dateiformate von Office (2007).
Öffnen Sie die Datei EmployeeControls.docx.zip .
Öffnen Sie den customXml-Ordner .
Öffnen Sie das Kontextmenü für item2.xml, und wählen Sie dann "Öffnen" aus.

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

Spalte	Wert
Mitarbeitername	Karina Leal
Einstellungsdatum	1. April 1999
Titel	Vorgesetzter

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.
Schützen Sie Teile eines Dokuments mithilfe von Inhaltssteuerelementen. Weitere Informationen finden Sie unter How to: Protect parts of documents by using content controls.