XmlDocument.CreateEntityReference(String) Methode

public:
 virtual System::Xml::XmlEntityReference ^ CreateEntityReference(System::String ^ name);

public virtual System.Xml.XmlEntityReference CreateEntityReference(string name);

abstract member CreateEntityReference : string -> System.Xml.XmlEntityReference
override this.CreateEntityReference : string -> System.Xml.XmlEntityReference

Public Overridable Function CreateEntityReference (name As String) As XmlEntityReference

Parameter

Gibt zurück

Die neue XmlEntityReference.

Ausnahmen

Beispiele

Im folgenden Beispiel werden zwei Entitätsverweisknoten erstellt und in ein XML-Dokument eingefügt.

using System;
using System.IO;
using System.Xml;

public class Sample
{
  public static void Main()
  {
    //Create the XmlDocument.
    XmlDocument doc = new XmlDocument();
    doc.LoadXml("<!DOCTYPE book [<!ENTITY h 'hardcover'>]>" +
                "<book genre='novel' ISBN='1-861001-57-5'>" +
                "<title>Pride And Prejudice</title>" +
                "<misc/>" +
                "</book>");

    //Create an entity reference node. The child count should be 0
    //since the node has not been expanded.
    XmlEntityReference entityref = doc.CreateEntityReference("h");
    Console.WriteLine(entityref.ChildNodes.Count );

    //After the node has been added to the document, its parent node
    //is set and the entity reference node is expanded.  It now has a child
    //node containing the entity replacement text.
    doc.DocumentElement.LastChild.AppendChild(entityref);
    Console.WriteLine(entityref.FirstChild.InnerText);

    //Create and insert an undefined entity reference node.  When the entity
    //reference node is expanded, because the entity reference is undefined
    //the child is an empty text node.
    XmlEntityReference entityref2 = doc.CreateEntityReference("p");
    doc.DocumentElement.LastChild.AppendChild(entityref2);
    Console.WriteLine(entityref2.FirstChild.InnerText);
  }
}

Option Explicit
Option Strict

Imports System.IO
Imports System.Xml

Public Class Sample
    
    Public Shared Sub Main()
        'Create the XmlDocument.
        Dim doc As New XmlDocument()
        doc.LoadXml("<!DOCTYPE book [<!ENTITY h 'hardcover'>]>" & _
                    "<book genre='novel' ISBN='1-861001-57-5'>"  & _
                    "<title>Pride And Prejudice</title>"  & _
                    "<misc/>"  & _
                    "</book>")
        
        'Create an entity reference node. The child count should be 0 
        'since the node has not been expanded.
        Dim entityref As XmlEntityReference = doc.CreateEntityReference("h")
        Console.WriteLine(entityref.ChildNodes.Count)
        
        'After the node has been added to the document, its parent node
        'is set and the entity reference node is expanded.  It now has a child
        'node containing the entity replacement text. 
        doc.DocumentElement.LastChild.AppendChild(entityref)
        Console.WriteLine(entityref.FirstChild.InnerText)
        
        'Create and insert an undefined entity reference node.  When the entity
        'reference node is expanded, because the entity reference is undefined
        'the child is an empty text node.
        Dim entityref2 As XmlEntityReference = doc.CreateEntityReference("p")
        doc.DocumentElement.LastChild.AppendChild(entityref2)
        Console.WriteLine(entityref2.FirstChild.InnerText)
    End Sub
End Class

Hinweise

Wenn die referenzierte Entität bekannt ist, wird die untergeordnete Liste des XmlEntityReference Knotens mit dem des entsprechenden XmlEntity Knotens identisch gemacht.

Die Namespaces, die im Ersetzungstext für den Entitätsverweis verwendet werden, sind gebunden, wenn das übergeordnete Element des Entitätsverweisknotens zuerst festgelegt ist (z. B. wenn der Entitätsverweisknoten in das Dokument eingefügt wird). Beispiel: In Anbetracht der folgenden Entität:

<!ENTITY a "<b>test</b>">

Wenn Sie aufrufen CreateEntityReference("a"), erhalten Sie einen einzelnen Knoten vom Typ "EntityReference" ohne untergeordnete Elemente zurück. Wenn Sie diesen Knoten als untergeordnetes Element des folgenden Knotens anfügen, <item xmlns="urn:1"/>wird zum Zeitpunkt des Aufrufs AppendChilddas übergeordnete Element des neu erstellten Entitätsverweisknotens festgelegt, und die untergeordneten Elemente werden in diesem Namespacekontext erweitert. Der untergeordnete Elementknoten b hat namespaceURI gleich urn:1. Die untergeordneten Knoten des Entitätsverweises bleiben unverändert, auch wenn Sie den Entitätsverweis an eine Stelle im Dokument verschieben, die einen anderen Standardnamespacekontext aufweist. Dies geschieht nicht für vorhandene Entitätsverweisknoten, wenn Sie sie entfernen und einfügen oder für Entitätsverweise, mit CloneNodedenen Sie klonen. Dies geschieht nur für neu erstellte Entitätsverweise.

Wenn die entsprechende Entität nicht im DocumentType definiert ist, wenn der Entitätsverweisknoten hinzugefügt wird, da der Entitätsverweis nicht definiert ist, ist der einzige untergeordnete Knoten ein leerer Textknoten.

Die integrierten Entitäten amp, lt, gt, apos und quot sind ebenfalls zulässig, und sie verfügen über einen untergeordneten Textknoten mit dem entsprechenden erweiterten Zeichenwert.

Obwohl diese Methode das neue Objekt im Kontext des Dokuments erstellt, wird das neue Objekt nicht automatisch der Dokumentstruktur hinzugefügt. Um das neue Objekt hinzuzufügen, müssen Sie explizit eine der Methoden zum Einfügen von Knoten aufrufen.

Gemäß der Empfehlung von W3C Extensible Markup Language (XML) 1.0 sind EntityReference-Knoten nur innerhalb von Element-, Attribut- und EntityReference-Knoten zulässig.