XmlDocument.CreateEntityReference(String) 方法

定義

命名空間:

System.Xml

組件:

System.Xml.ReaderWriter.dll

組件:

System.Xml.dll

組件:

netstandard.dll

建立具有指定名稱的 XmlEntityReference。

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

參數

name

String

實體參考的名稱。

傳回

XmlEntityReference

新的 XmlEntityReference。

例外狀況

ArgumentException

不正確的名稱 (例如以 '#' 開頭的名稱無效)。

範例

下列範例會建立兩個實體參考節點，並將其插入 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

備註

如果已知的參考實體，則節點的 XmlEntityReference 子清單會與對應 XmlEntity 節點的子清單相同。

實體參考的取代文字中使用的命名空間會在實體參考節點的父系第一次設定時系結 (例如，當實體參考節點插入檔) 時。 例如，假設有下列實體：

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

如果您呼叫 CreateEntityReference("a") 時，會傳回沒有子系之 EntityReference 類型的單一節點。 如果您將此節點附加為下列節點的子系，

<item xmlns="urn:1"/>  

然後，在呼叫 AppendChild 時，會設定新建立之實體參考節點的父節點，而且子系會在此命名空間內容中展開。 子專案節點 b 的 NamespaceURI 會等於 urn:1 。 即使您將實體參考移至具有不同預設命名空間內容之檔中的位置，實體參考的子節點仍維持不變。 當您移除和插入現有實體參考節點，或是使用 CloneNode 複製的實體參考時，不會發生這種情況。 它只會針對新建立的實體參考進行。

如果新增實體參考節點時，未在 DocumentType 中定義對應的實體，因為未定義實體參考，其唯一的子節點會是空的文位元組點。

也允許內建實體 amp、lt、gt、apos 和 quot，而且會有具有適當展開字元值的子文位元組點。

雖然這個方法會在檔的內容中建立新的 物件，但不會自動將新物件加入檔樹狀結構。 若要新增物件，您必須明確呼叫其中一個節點插入方法。

根據 W3C Extensible Markup Language (XML) 1.0 建議，EntityReference 節點只能在 Element、Attribute 和 EntityReference 節點內使用。