Umbraco/示例與文章/Dot Net 控制元件/在 Umbraco 中使用 Dot NET 控制元件
最初來自http://www.umbraco.org/media/42a0202c-b0ba-4f84-bcf1-64dfd5230322-usingcontrolswithumbraco.pdf上的 PDF 檔案
本教程是即將推出的 Umbraco 開發者休息室產品的預告片。如果您喜歡您閱讀的內容，您一定會喜歡“休息室”。它是一個包含類似教程的網站，其中包括最佳實踐、示例程式碼等等。Umbraco 開發者休息室將於 2005 年第二季度釋出，並將以每年 300 歐元/使用者的低廉年費（或每月 30 歐元）提供。
您可以使用 .NET 控制元件與 umbraco 協同工作，無論是使用者控制元件（.ascx 檔案）還是自定義控制元件（.dll），都可以使用宏。您甚至可以透過使用公共屬性和宏元素與您的控制元件進行通訊。
本文件將告訴您如何實現這兩種型別的控制元件以及如何進行通訊。
首先，您需要複製您的控制元件。無論是使用者控制元件還是自定義控制元件，您都需要將程式集（dll）複製到 umbraco 安裝的 /bin 資料夾中。如果是使用者控制元件，您還需要複製 .ascx 檔案。您的安裝程式中已經包含一個 /usercontrols 資料夾，我們建議您使用它，但您也可以將其放置在應用程式中的任何位置。
我們有一個名為 HelloWorld 的使用者控制元件，它是在 Visual Basic.NET 中編寫的，其中包含一個文字框和一個按鈕。讓我們看一下專案資料夾中的檔案
我們需要的是專案根目錄下的 HelloWorld.ascx 檔案，以及儲存在 bin 資料夾中的 HelloWorld.dll 檔案。
我們將把 HelloWorld.ascx 複製到 /usercontrols/HelloWorld.ascx，並將 HelloWorld.dll 複製到 /bin/HelloWorld.dll。現在我們已經準備好使用宏將使用者控制元件註冊到 umbraco 中了！
為了能夠直接從 umbraco 中使用 .NET 控制元件，有必要將它們註冊到一個宏中。因此，開啟 umbraco，進入“開發人員”部分，右鍵單擊宏資料夾。選擇建立，並將其命名為“HelloWorld”。
現在，在開啟的宏資料夾中選擇 HelloWorld 宏，並在名為“型別”的欄位中輸入“usercontrols/HelloWorld.ascx”，如以下螢幕截圖所示
點選儲存按鈕，您就可以像使用其他宏一樣使用 HelloWorld.ascx 使用者控制元件了。就是這樣！如果您使用的是程式集，則程式集應該是您的 dll 的名稱（不帶 dll 副檔名），並且型別應該是包括名稱空間的完整名稱！
透過在您的控制元件中建立公共屬性，並將它們與宏元素匹配，您就可以直接從 umbraco 內部與您的控制元件進行通訊。umbraco 甚至會在插入宏時建立 UI。重要的是，宏元素的別名要與公共屬性的名稱匹配，並注意大小寫敏感性！
首先，讓我們在 HelloWorld 使用者控制元件中建立一個公共屬性，並將其也命名為“HelloWorld”。如果未回發，我們將把文字框內的文字設定為公共屬性的內容，以下是使用 Visual Basic.NET 進行操作的簡單方法，您可以使用任何受 .NET 支援的語言（如 C# 或 Delphi.NET）
編譯並再次複製上面描述的檔案。
接下來，我們需要建立一個宏元素，因此返回 umbraco 並編輯“HelloWorld”宏。複選框（缺少標籤）表示元素在插入宏時是否應該向使用者顯示，因此選中它。元素的別名應該與公共屬性的名稱完全相同，並且注意大小寫敏感性。如果您點選“瀏覽屬性”按鈕，您可以選擇您想要的公共屬性，umbraco 會建立它們。
元素的名稱是使用者在插入宏時在 umbraco 內部看到的名稱，因此輸入一些有意義的名稱，例如“回發時的訊息”。接下來，確定要建立的元素型別，在與 .NET 控制元件一起使用時，它只與使用者將看到的 UI 有關（不同於使用 XSLT 宏，其中型別會影響宏將使用的 XML）。選擇“文字”，因為我們將讓使用者輸入一條訊息。點選新增。
就這樣，現在 umbraco 可以與您的控制元件進行通訊了！讓我們試一試！
Umbraco 預設情況下不會將 .NET 伺服器端表單插入到您的內容中。如果您在控制元件中使用伺服器端元素（帶有屬性 runat=”server”），那麼在模板的頂部和底部插入 <?ASPNET_FORM> umbraco 標籤非常重要。
要插入包含 .NET 控制元件的宏，您需要進入“設定”內的模板部分，或者直接在編輯器中插入。在本示例中，我們將將其插入模板中。
開啟一個模板，例如如果您使用的是示例站點，則開啟“Textpage”模板。在“<?UMBRACO_GETITEM/>”標籤之前新建一行，然後點選工具欄上的插入宏按鈕（）。選擇“HelloWorld”宏，您應該看到以下內容
輸入您喜歡的任何內容，然後點選確定。您的模板現在應該看起來像這樣
點選儲存按鈕，然後檢視使用您的宏的頁面。它應該看起來像這樣
嘗試更改文字框中的文字，然後點選按鈕。Umbraco 甚至會處理狀態。
如果您在一個頁面上使用多個相同的 .NET 控制元件宏的例項，或者您只是想確保分配給控制元件的 Id，則可以在 <?UMBRACO_MACRO> 標籤中新增一個額外的屬性，稱為“controlID”。為此，上面的標籤將如下所示
<?UMBRACO_MACRO macroID=”7” HelloWorld=”It worked!” controlID=”HelloWorld1”></?UMBRACO_MACRO>
如您所見，在 Umbraco 中使用 .NET 控制元件非常容易，而且您可以使用現有的、不是為 Umbraco 而製作的控制元件。盡情享受…
為了成功編譯 Umbraco 2.xx 的使用者控制元件，請從 MSDN 下載Visual Studio 2005 Web 應用程式專案。安裝完附加元件後，您可以像在以前的 Visual Studio.NET 版本中一樣建立專案。
在為 Umbraco 開發時，請特別注意，您在單獨的程式碼檔案中使用舊的程式碼隱藏指令，而不是 .NET 2.0 引入的新程式碼檔案指令
使用 `umbraco.library.RenderMacroContent` 方法，你可以渲染一個控制元件並建立一個 "遞迴宏"。
使用 Dot NET 控制元件則不可行，因為在 `RenderMacroContent` 中建立的控制元件會被轉換為字串，然後丟失：它不會被新增到 `Page.Controls` 中，因此不會呼叫你控制元件的任何處理程式。