XmlDocument.CreateEntityReference(String) 方法

定義

命名空間:

System.Xml

組件:

netstandard.dll, System.Xml.ReaderWriter.dll

來源:

XmlDocument.cs

建立 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;
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。 即使你將實體參考移到文件中預設命名空間不同的位置，實體參考的子節點依然保持不變。 當你移除並插入現有實體參考節點時，或是用 CloneNodeS 克隆的實體參考，這些問題都不會發生。 這只會發生在新建立的實體參考時。

如果在新增實體參考節點時，DocumentType 中未定義對應的實體，因為該實體參考未被定義，其唯一的子節點將是空的文字節點。

內建的實體 amp、lt、gt、apos 和 quot 也是允許的，並且它們會有一個子文字節點，並帶有適當的展開字元值。

雖然此方法會在文件上下文中建立新物件，但不會自動將新物件加入文件樹。 要新增物件，必須明確呼叫其中一個節點插入方法。

根據 W3C 可擴充標記語言（XML）1.0 建議，EntityReference 節點僅允許在元素、屬性及 EntityReference 節點內使用。