重學ASP.NET Core 中的標記幫助程序

標記幫助程序是什麼

標記幫助程序使服務器端代碼能夠在 Razor 文件中參與建立和呈現 HTML 元素。 例如，內置的 ImageTagHelper 能夠將版本號追加到圖片名稱。  每當圖片發生變化時，服務器都會爲圖像生成一個新的惟一版本號，所以客戶端總能得到當前圖像（而不是過期的緩存圖像）。

做者：依樂祝
原文連接：http://www.javashuo.com/article/p-xfqqzhll-kg.html

標記幫助程序的做用域是如何控制的

標記幫助程序做用域由 @addTagHelper、@removeTagHelper 和「!」選擇退出字符等聯合控制。下面就一一的進行相關的介紹吧。

使用 @addTagHelper 添加標記幫助程序

@addTagHelper 指令讓視圖可使用標記幫助程序。 在這種狀況下，視圖文件是_pages/ViewImports，默認狀況下，它由_pages_文件夾和子文件夾中的全部文件繼承，這使得標記幫助程序可用。 
這裏公開標記幫助程序有兩種方式，以下所示：
第一種：使用通配符語法（" * "）指定指定程序集（AspNetCore）中的全部標記幫助程序均可用於_Views_目錄及其子目錄中的每一個視圖文件。

@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers

第二種：使用標記幫助程序的徹底限定名，添加某個特定的標記幫助程序。

@addTagHelper AuthoringTagHelpers.TagHelpers.EmailTagHelper, AuthoringTagHelpers

說明：@addTagHelper 後第一個參數指定要加載的標記幫助程序（咱們使用「*」指定加載全部標記幫助程序），第二個參數「Microsoft.AspNetCore.Mvc.TagHelpers」指定包含標記幫助程序的程序集。 
注：Microsoft.AspNetCore.Mvc.TagHelpers 是內置 ASP.NET Core 標記幫助程序的程序集。

@removeTagHelper 刪除標記幫助程序

@removeTagHelper 與 @addTagHelper 具備相同的兩個參數，它會刪除以前添加的標記幫助程序。 例如，應用於特定視圖的 @removeTagHelper 會刪除該視圖中的指定標記幫助程序。 在 Views/Folder/_ViewImports.cshtml 文件中使用 @removeTagHelper，將從 Folder 中的全部視圖刪除指定的標記幫助程序。

使用 _ViewImports.cshtml  文件控制標記幫助程序做用域

可將 _ViewImports.cshtml 添加到任何視圖文件夾，視圖引擎將同時應用該文件和 Views/_ViewImports.cshtml 文件中的指令。

說明：

1. 若是爲 Home 視圖添加空的 Views/Home/_ViewImports.cshtml 文件，則不會發生任何更改，由於 _ViewImports.cshtml 文件是附加的。
2. 添加到 Views/Home/_ViewImports.cshtml 文件（不在默認 Views/_ViewImports.cshtml 文件中）的任何 @addTagHelper 指令，都只會將這些標記幫助程序公開給 Home 文件夾中的視圖。

選擇退出字符（「!」）元素級別退出標記幫助程序

使用標記幫助程序選擇退出字符（「!」），可在元素級別禁用標記幫助程序。 例如，使用標記幫助程序選擇退出字符在 <span> 中禁用 Email 驗證：

<!span asp-validation-for="Email" class="text-danger"></!span>

說明：
須將標記幫助程序選擇退出字符應用於開始和結束標記。 （將選擇退出字符添加到開始標記時，Visual Studio 編輯器會自動爲結束標記添加相應字符）。 
添加選擇退出字符後，元素和標記幫助程序屬性再也不以獨特字體顯示。

使用 @tagHelperPrefix 闡明標記幫助程序用途

@tagHelperPrefix 指令可指定一個標記前綴字符串，以啓用標記幫助程序支持並闡明標記幫助程序用途。 例如，能夠將如下標記添加到 Views/_ViewImports.cshtml 文件：

@tagHelperPrefix th:

在如下代碼圖像中，標記幫助程序前綴設置爲 th:，因此只有使用前綴 th: 的元素才支持標記幫助程序（可以使用標記幫助程序的元素以獨特字體顯示）。 <label> 和 <input> 元素具備標記幫助程序前綴，可以使用標記幫助程序，而 <span> 元素則相反。

適用於 @addTagHelper 的層次結構規則也適用於 @tagHelperPrefix。

標記幫助程序的 Intellisense 支持

在 Visual Studio 中建立新的 ASP.NET Core web 應用時，它將添加AspNetCore Razor 的NuGet 包 。它 是添加標記幫助程序的工具包。
假設編寫 HTML <label> 元素。 只要在 Visual Studio 編輯器中輸入 <l，IntelliSense 就會顯示匹配的元素：

不只會得到 HTML 幫助，還會有圖標（下方帶有「<>」的「@" symbol with "）

將該元素標識爲標記幫助程序的目標。 純 HTML 元素（如 `fieldset`）顯示「<>」圖標。
純 HTML ` ` 標記以棕色字體顯示 HTML 標記（使用默認 Visual Studio 顏色主題時），以紅色字體顯示屬性，並以藍色字體顯示屬性值。

輸入 <label 後，IntelliSense 會列出可用的 HTML/CSS 屬性和以標記幫助程序爲目標的屬性：

經過 IntelliSense 語句完成功能，按 Tab 鍵便可用選擇的值完成語句：

只要輸入標記幫助程序屬性，標記和屬性字體就會更改。 若是使用默認的 Visual Studio「藍色」或「淺色」顏色主題，則字體是粗體紫色。 若是使用「深色」主題，則字體爲粗體青色。 本文檔中的圖像在使用默認主題時截取的。

可在雙引號 ("") 內輸入 Visual Studio CompleteWord 快捷方式（默認值爲 Ctrl+空格鍵），便可使用 C#，就像在 C# 類中同樣。IntelliSense 會顯示頁面模型上的全部方法和屬性。 因爲屬性類型是 ModelExpression，因此這些方法和屬性可用。 在下圖中，我正在編輯 Register 視圖，因此 RegisterViewModel 是可用的。

IntelliSense 會列出頁面上模型可用的屬性和方法。 豐富 IntelliSense 環境可幫助選擇 CSS 類：

自定義標記幫助程序元素字體

能夠從 "工具" "選項" "環境" " > Options > Environment > 字體和顏色" 中自定義字體和着色：

實例演示如何在ASP.NET Core中建立標記幫助程序

標記幫助程序是實現 ITagHelper 接口的任何類。 可是，在創做標記幫助程序時，一般從 TagHelper 派生，這樣能夠訪問 Process 方法。

1. 建立一個名爲 AuthoringTagHelpers 的新 ASP.NET Core 項目。注： 此項目不須要身份驗證。
   
2. 建立一個名爲「TagHelpers」的文件夾來保存標記幫助程序。注： TagHelpers 文件夾不是必需的，但它是合理的約定。

如今讓咱們開始編寫一些簡單的標記幫助程序。

EmailTagHelper 標記幫助程序

若是你正在編寫博客引擎，而且須要它將營銷、支持和其餘聯繫人的電子郵件所有發送到同一個域，則可能須要這樣的一個標記幫助程序。
以下所示，先上代碼：

using Microsoft.AspNetCore.Razor.TagHelpers;
using System.Threading.Tasks;

namespace AuthoringTagHelpers.TagHelpers
{
    public class EmailTagHelper : TagHelper
    {
        public override Task ProcessAsync(TagHelperContext context, TagHelperOutput output)
        {
            output.TagName = "a";    // Replaces <email> with <a> tag
            var address = MailTo + "@" + EmailDomain;
        	output.Attributes.SetAttribute("href", "mailto:" + address);
        	output.Content.SetContent(address);
            return Task.CompletedTask;
        }
    }
}

說明：

1. 標記幫助程序使用面向根類名稱的元素的命名約定（減去類名稱的 TagHelper 部分）。 在此示例中， EmailTagHelper的根名稱爲_email_，所以 <email> 標記將針對。
2. EmailTagHelper 類從 TagHelper 派生。 TagHelper 類提供編寫標記幫助程序的方法和屬性。
3. 重寫的 ProcessAsync 方法控制標記幫助程序在執行時的操做。 TagHelper 類還提供具備相同參數的同步版本 (Process)。
4. 類名稱的後綴是 TagHelper，這不是必需的，但被認爲是約定的最佳作法。 可將類聲明爲：public class Email : TagHelper
5. 標記幫助程序採用 Pascal 大小寫格式的類和屬性名將轉換爲各自相應的短橫線格式。 所以，要使用 MailTo 屬性，請使用 <email mail-to="value"/> 等效項。
6. 最後一行爲EmailTagHelper標記幫助程序設置已完成的內容。
7. SetAttribute 是添加屬性的語法，只要屬性集合中當前不存在 href 屬性，該方法就適用於此屬性。

接下來然咱們在Razor頁面上應用此標記幫助程序吧。
使用如下更改更新 Views/Home/Contact.cshtml 文件中的標記:

@using AuthoringTagHelpers
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@addTagHelper AuthoringTagHelpers.TagHelpers.EmailTagHelper, AuthoringTagHelpers
@{
    ViewData["Title"] = "Contact Copy";
}
<h2>@ViewData["Title"].</h2>
<h3>@ViewData["Message"]</h3>

<address>
    One Microsoft Way Copy Version <br />
    Redmond, WA 98052-6399<br />
    <abbr title="Phone">P:</abbr>
    425.555.0100
</address>

<address>
    <strong>Support:</strong><email mail-to="Support"></email><br />
    <strong>Marketing:</strong><email mail-to="Marketing"></email>
</address>

說明：

1. 開頭的 @addTagHelper 是添加對應的標記幫助程序引用，文章開頭已經進行了相關闡述
2. 第18，19行代碼 標記引用了咱們上面編寫的    EmailTagHelper 標記幫助程序。
3. mail-to 屬性是標記幫助程序採用 Pascal 大小寫格式的類和屬性名將轉換爲各自相應的短橫線格式。 所以，要使用 MailTo 屬性，必須使用  的等效項。

這時候運行下程序，能夠看到生成對應的html標籤了：

<a href="mailto:Support@contoso.com">Support@contoso.com</a>
<a href="mailto:Marketing@contoso.com">Marketing@contoso.com</a>

在標記幫助程序中使用實體模型

1. 添加「Models」文件夾**。
   
2. 將如下 WebsiteContext 類添加到「模型」文件夾：

using System;

namespace AuthoringTagHelpers.Models
{
    public class WebsiteContext
    {
        public Version Version { get; set; }
        public int CopyrightYear { get; set; }
        public bool Approved { get; set; }
        public int TagsToShow { get; set; }
    }
}

3. 將如下 WebsiteInformationTagHelper 類添加到「TagHelpers」文件夾。

using System;
using AuthoringTagHelpers.Models;
using Microsoft.AspNetCore.Razor.TagHelpers;

namespace AuthoringTagHelpers.TagHelpers
{
    public class WebsiteInformationTagHelper : TagHelper
    {
        public WebsiteContext Info { get; set; }

      public override void Process(TagHelperContext context, TagHelperOutput output)
      {
         output.TagName = "section";
         output.Content.SetHtmlContent(
$@"<ul><li><strong>Version:</strong> {Info.Version}</li>
<li><strong>Copyright Year:</strong> {Info.CopyrightYear}</li>
<li><strong>Approved:</strong> {Info.Approved}</li>
<li><strong>Number of tags to show:</strong> {Info.TagsToShow}</li></ul>");
         output.TagMode = TagMode.StartTagAndEndTag;
      }
   }
}

4. 將如下標記添加到 About.cshtml 視圖**。 突出顯示的標記顯示 Web 站點信息。

@using AuthoringTagHelpers.Models
@{
    ViewData["Title"] = "About";
    WebsiteContext webContext = new WebsiteContext {
                                    Version = new Version(1, 3),
                                    CopyrightYear = 1638,
                                    Approved = true,
                                    TagsToShow = 131 };
}
<h2>@ViewData["Title"].</h2>
<h3>@ViewData["Message"]</h3>

<p bold>Use this area to provide additional information.</p>

<bold> Is this bold?</bold>

<h3> web site info </h3>
<website-information info="webContext" />

說明：
在下面的Razor顯示的標記中：
<website-information info="webContext" /> 
Razor知道 info 屬性是一個類，而不是字符串，而且您想要編寫 c # 代碼。 編寫任何非字符串標記幫助程序屬性時，都不該使用 @ 字符。

5. 運行應用，並導航到「關於」視圖便可查看 Web 站點信息。

總結

本文首先帶着你們回顧了一下標記幫助程序的一些概念，接着給你們介紹了標記幫助程序做用域的注意事項來爲接下來的實例演練作準備。而後給你們介紹了標記幫助程序強大的 Intellisense 支持，讓咱們在開發中事半功倍，如虎添翼！最後就是經過實例代碼來作兩個標記幫助程序的小例子加深咱們的理解。但願對你們有所幫助！
接下來我會介紹下微軟官方提供的一些經常使用標記幫助程序，有興趣的朋友能夠關注下。


參考文檔：

1. https://docs.microsoft.com/zh-cn/aspnet/core/mvc/views/tag-helpers/intro?view=aspnetcore-3.1
2. https://docs.microsoft.com/zh-cn/aspnet/core/mvc/views/tag-helpers/authoring?view=aspnetcore-3.1