ASP.NET 控件開發（三）：標籤內容解析控制——ParseChildren 與 ControlBuilder

控件標籤內容可解析為屬性值（如 TextBox.Text）或子控件集合（如 Panel.Controls），透過 ParseChildrenAttribute 與 ControlBuilderAttribute 精確控制解析行為。

ParseChildrenAttribute 四種建構式

• Control 基類預設 ChildrenAsProperties=false（解析為子控件）
• WebControl 標記 [ParseChildren(true, "Text")]，預設解析為 Text 屬性

PersistenceModeAttribute 控制屬性序列化方式

DropDownList 完整標記範例

[ParseChildren(true, "Items")]
[DefaultProperty("Items")]
public class DropDownList : WebControl
{
    [PersistenceMode(PersistenceMode.InnerProperty)]
    public ListItemCollection Items { get; }
}

public class ListItem
{
    [PersistenceMode(PersistenceMode.EncodedInnerDefaultProperty)]
    public string Text { get; set; }
}

解析：Items 為集合屬性用 InnerProperty（巢狀標籤），ListItem.Text 為字串用 EncodedInnerDefaultProperty（內部文字自動編碼）。

解析為子控件的兩種方式

1. AddParsedSubObject（執行階段）

protected override void AddParsedSubObject(object obj)
{
    if (obj is LiteralControl literal)
        Text = literal.Text;  // 純文字內容存入 Text 屬性
    else
        throw new ArgumentException("僅允許靜態文字內容");
}

缺點：每次請求都執行，效率較低。

2. 自訂 ControlBuilder（解析階段，一次性）

[ControlBuilder(typeof(MyControlBuilder))]
public class MyControl : Control { }

public class MyControlBuilder : ControlBuilder
{
    public override bool AllowWhitespaceLiterals() => false;  // 去除首尾空白
    public override bool HtmlDecodeLiterals() => true;        // 移除 HTML 編碼
}

優點：僅在頁面編譯/解析階段執行一次，效能最佳。

最佳實踐

• 繼承 WebControl 且需自訂解析：標記 [ParseChildren(false)] + [ControlBuilder(...)]
• 簡單文字屬性：[ParseChildren(true, "PropertyName")] + [PersistenceMode(EncodedInnerDefaultProperty)]
• 集合/複雜屬性：InnerProperty + 子類別標記對應屬性