XmlDocument.CreateEntityReference(String) Methode

Referenz

Definition

Namespace:: System.Xml

Assembly:: System.Xml.ReaderWriter.dll

Assembly:: System.Xml.dll

Assembly:: netstandard.dll

Wichtig

Einige Informationen beziehen sich auf Vorabversionen, die vor dem Release ggf. grundlegend überarbeitet werden. Microsoft übernimmt hinsichtlich der hier bereitgestellten Informationen keine Gewährleistungen, seien sie ausdrücklich oder konkludent.

Erstellt eine XmlEntityReference mit dem angegebenen Namen.

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

name: String

Der Name des Entitätsverweises.

Gibt zurück

XmlEntityReference

Die neue XmlEntityReference.

Ausnahmen

ArgumentException

Der Name ist ungültig (z. B. sind Namen ungültig, die mit "#" beginnen.)

Beispiele

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

#using <System.Xml.dll>

using namespace System;
using namespace System::IO;
using namespace System::Xml;
int main()
{
   
   //Create the XmlDocument.
   XmlDocument^ doc = gcnew 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 );
}

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 identisch mit dem des entsprechenden XmlEntity Knotens gemacht.

Die namespaces, die im Ersatztext für den Entitätsverweis verwendet werden, sind an den Zeitpunkt gebunden, zu dem das übergeordnete Element des Entitätsverweisknotens zuerst festgelegt ist (z. B. wenn der Entitätsreferenzknoten in das Dokument eingefügt wird). Geben Sie beispielsweise die folgende Entität an:

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

Wenn Sie aufrufen, erhalten Sie CreateEntityReference("a") einen einzelnen Knoten des Typs EntityReference ohne untergeordnete Elemente zurück. Wenn Sie diesen Knoten als untergeordnetes Element des folgenden Knotens anfügen,

<item xmlns="urn:1"/>

Anschließend AppendChildwird das übergeordnete Element des neu erstellten Entitätsreferenzknotens festgelegt, und die untergeordneten Elemente werden im Namespacekontext erweitert. Der untergeordnete Elementknoten b verfügt über NamespaceURI gleich urn:1. Die untergeordneten Knoten des Entitätsverweis bleiben auch dann identisch, wenn Sie den Entitätsbezug auf einen Ort im Dokument verschieben, der einen anderen Standardnamespacekontext aufweist. Dies geschieht nicht für vorhandene Entitätsreferenzknoten, wenn Sie sie entfernen und einfügen oder für Entitätsbezüge, mit denen Sie klonen CloneNode. Es geschieht nur für neu erstellte Entitätsbezüge.

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 sein einziger untergeordneter Knoten ein leerer Textknoten.

Die integrierten Entitäten amp, lt, gt, apos und quot sind auch 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 zur Dokumentstruktur hinzugefügt. Um das neue Objekt hinzuzufügen, müssen Sie explizit eine der Methoden zum Einfügen von Knoten aufrufen.

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

Gilt für