XmlDocument.CreateEntityReference(String) Metoda

Reference

Definice

Obor názvů:: System.Xml

Sestavení:: System.Xml.ReaderWriter.dll

Sestavení:: System.Xml.dll

Sestavení:: netstandard.dll

Důležité

Některé informace platí pro předběžně vydaný produkt, který se může zásadně změnit, než ho výrobce nebo autor vydá. Microsoft neposkytuje žádné záruky, výslovné ani předpokládané, týkající se zde uváděných informací.

Vytvoří se XmlEntityReference zadaným názvem.

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

Parametry

name: String

Název odkazu na entitu.

Návraty

XmlEntityReference

Nový XmlEntityReference.

Výjimky

ArgumentException

Název je neplatný (například názvy začínající na #jsou neplatné.)

Příklady

Následující příklad vytvoří dva referenční uzly entity a vloží je do dokumentu XML.

#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

Poznámky

Pokud je odkazovaná entita známá, podřízený seznam XmlEntityReference uzlu je stejný jako u odpovídajícího XmlEntity uzlu.

Obory názvů použité v náhradním textu odkazu na entitu jsou vázané v okamžiku, kdy je nadřazený uzel odkazu entity poprvé nastaven (například při vložení referenčního uzlu entity do dokumentu). Například s ohledem na následující entitu:

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

Pokud zavoláte CreateEntityReference("a") zpět jeden uzel typu EntityReference bez podřízených položek. Pokud tento uzel připojíte jako podřízený uzel následujícího uzlu,

<item xmlns="urn:1"/>

v době volání AppendChildje nadřazený nově vytvořený uzel odkazu na entitu nastaven a podřízené položky se rozbalí v tomto kontextu oboru názvů. Uzel podřízeného elementu b bude mít identifikátor NamespaceURI rovna urn:1. Podřízené uzly odkazu na entitu zůstanou stejné i v případě, že přesunete odkaz na entitu na místo v dokumentu s jiným výchozím kontextem oboru názvů. K tomu nedojde u existujících uzlů odkazů na entity, když je odeberete a vložíte je nebo pro odkazy na entity, se kterými klonujete CloneNode. Stává se to jenom u nově vytvořených odkazů na entity.

Pokud odpovídající entita není definována v DocumentType při přidání referenčního uzlu entity, protože odkaz na entitu není definován, jeho jediný podřízený uzel bude prázdný textový uzel.

Také jsou povoleny předdefinované entity amp; lt, gt, apos a quot a budou mít podřízený textový uzel s příslušnou rozšířenou hodnotou znaku.

I když tato metoda vytvoří nový objekt v kontextu dokumentu, nepřidá automaticky nový objekt do stromu dokumentu. Chcete-li přidat nový objekt, musíte explicitně volat jednu z metod vložení uzlu.

Podle doporučení W3C Extensible Markup Language (XML) 1.0 jsou uzly EntityReference povoleny pouze v uzlech Element, Attribute a EntityReference.

Platí pro