asp.net core 2.1 TagHelpers

简介

Tag Helpers 提供了在视图中更改和增强现有HTML元素的功能。将它们添加到视图中，会经过Razor模板引擎处理并创建一个HTML，之后再返回给浏览器。有一些Tag Helpers，其实作为元素或实际的标签（如environment，cache等）。

它们使用HTML方式编写，同时利用了Razor的强大功能、C#的简洁和HTML的友好性。由于使用Tag Helpers感觉如此自然，看起来像标准的HTML，前端开发人员也可以轻松地适应，不需要学习C#语法；此外，它们可以在现有元素范围内获得完美的智能提示支持。

看一下简单的例子，注意上下两行代码的区别：

<img src="~/images/banner1.svg" />
<img src="~/images/banner1.svg" asp-append-version="true"  />

它们可能会使您想到Razor中的HTML Helpers，的确，它们也具有部分相同的功能，但是，Tag Helpers使用起来更加自然；我们通常会使用它们来扩展现有HTML元素，使用HTML Helpers是用来创建一个新的HTML元素。

内置Tag Helpers列表

表单相关Tag Helpers：

Form
FormAction
Input
Label
Option
Select
TextArea
ValidationMessage
ValidationSummary

缓存：

Cache
Distributed

其他：

Image
Anchor
Script
Link
Environment

注意：所有内置的Tag Helpers以 asp- 作为前缀。

其他标记详解

<!--<img src="/images/banner1.svg?v=GaE_EmkeBf-yBbrJ26lpkGd4jkOSh1eVKJaNOw9I4uk">-->
<img src="~/images/banner1.svg" asp-append-version="true"  />

<!--<a href="/Home/About">home/index</a>-->
<a asp-controller="Home" asp-action="About">home/About</a>


<!--asp-src-include、asp-src-exclude-->
<!--
<script src="/lib/jquery/dist/jquery.js"></script>
<script src="/lib/jquery/dist/jquery.min.js"></script>
<script src="/lib/jquery/dist/test/aa.js"></script>     ----排除
<script src="/lib/jquery/dist/test/aa.min.js"></script> ----排除
<script src="/lib/jquery/dist/test2/bb.js"></script>
-->
<script asp-src-include="~/lib/jquery/dist/**/**.js" asp-src-exclude="~/lib/jquery/dist/test/**.js"></script>


<!--
 这里src不可用。
<script src="https://cdn.bootcss.com/jquery1/3.3.1/jquery.js"></script>
<script>(window.jQuery && window.jQuery.fn||document.write("u003Cscript src=u0022/lib/jquery/dist/jquery.jsu0022u003Eu003C/scriptu003E"));</script>
<script src="/lib/jquery/dist/jquery.js"></script>
-->
<script src="https://cdn.bootcss.com/jquery1/3.3.1/jquery.js"
        asp-fallback-src="~/lib/jquery/dist/jquery.js"
        asp-fallback-test="window.jQuery && window.jQuery.fn"></script>


<br/>

<!--
environment:
names 采用单个宿主环境名称或以逗号分隔的宿主环境名称列表，用于触发已包含内容的呈现。
-->
<environment names="Staging,Development">
    <strong>HostingEnvironment.EnvironmentName is Staging or Production</strong>
</environment>

<environment include="Development">
    this will run in Development <br />
</environment>

<environment include="Production">
    this will run in Production <br />
</environment>

生成

<!--<img src="/images/banner1.svg?v=GaE_EmkeBf-yBbrJ26lpkGd4jkOSh1eVKJaNOw9I4uk">-->
<img src="/images/banner1.svg?v=GaE_EmkeBf-yBbrJ26lpkGd4jkOSh1eVKJaNOw9I4uk">

<!--<a href="/Home/About">home/index</a>-->
<a href="/Home/About">home/About</a>


<!--asp-src-include、asp-src-exclude-->
<!--
<script src="/lib/jquery/dist/jquery.js"></script>
<script src="/lib/jquery/dist/jquery.min.js"></script>
<script src="/lib/jquery/dist/test/aa.js"></script>     ----排除
<script src="/lib/jquery/dist/test/aa.min.js"></script> ----排除
<script src="/lib/jquery/dist/test2/bb.js"></script>
-->
<script src="/lib/jquery/dist/jquery.js"></script>
<script src="/lib/jquery/dist/jquery.min.js"></script>
<script src="/lib/jquery/dist/test2/bb.js"></script>


<!--
 这里src不可用。
<script src="https://cdn.bootcss.com/jquery1/3.3.1/jquery.js"></script>
<script>(window.jQuery && window.jQuery.fn||document.write("u003Cscript src=u0022/lib/jquery/dist/jquery.jsu0022u003Eu003C/scriptu003E"));</script>
<script src="/lib/jquery/dist/jquery.js"></script>
-->
<script src="https://cdn.bootcss.com/jquery1/3.3.1/jquery.js"></script>
<script>(window.jQuery && window.jQuery.fn||document.write("u003Cscript src=u0022/lib/jquery/dist/jquery.jsu0022u003Eu003C/scriptu003E"));</script>


<br>

<!--
environment:
names 采用单个宿主环境名称或以逗号分隔的宿主环境名称列表，用于触发已包含内容的呈现。
-->
    <strong>HostingEnvironment.EnvironmentName is Staging or Production</strong>
    this will run in Development <br>

Script and Link Tag Helpers

这两个Tag Helpers使我们在HTML中添加JS和CSS引用更容易；如果我们使用像CDN这样的外部资源，还能使用本地备用的URL地址。
此外，它们大大简化了使用全局模式时引用大量资源文件。
就像image标签助手，Script和Link Tag Helpers也可以帮助我们缓存资源文件。

<!--
 这里src不可用。
<script src="https://cdn.bootcss.com/jquery1/3.3.1/jquery.js"></script>
<script>(window.jQuery && window.jQuery.fn||document.write("u003Cscript src=u0022/lib/jquery/dist/jquery.jsu0022u003Eu003C/scriptu003E"));</script>
<script src="/lib/jquery/dist/jquery.js"></script>
-->
<script src="https://cdn.bootcss.com/jquery1/3.3.1/jquery.js"
        asp-fallback-src="~/lib/jquery/dist/jquery.js"
        asp-fallback-test="window.jQuery && window.jQuery.fn"></script>

这个例子显示我们引用了来自 aspnetcdn 的 Bootstrap JS文件。如果该网站不可用，将引用本地文件，使用 asp-fallback-src Tag Helper；什么是 asp-fallback-test？它是一种知道是否会使用本地备用的方法，在这个示例中，我们使用一个特定的代码来检查Bootstrap的JS功能是否存在。

如果 asp-fallback-test 中的表达式返回false（falsy），将使用 asp-fallback-src 指定的源文件。

缓存 TagHelper

首先说一下 <cache> Tag Helper。与其它Tag Helper不同，其它Tag Helper被当作属性使用，缓存Tag Helper作为标签使用 - <cache>。它根据其属性指定的选项，将包含的内容缓存到内存中。

expires-after - 最常用的一个，它表示缓存内容过期的时间段（timespan）
expires-on - 过期的时间点
expires-sliding – 访问超过某个时间段后就过期（timespan）

vary-by 属性

它基于当前请求的查询参数创建唯一的缓存键。

<cache expires-after="@TimeSpan.FromSeconds(10)" vary-by-query="queryParam1">
    缓存10秒
    this will be cached in server memory. @DateTime.Now.ToString("hh:mm:ss tt")
</cache>

http://localhost:5000/home/cache?queryParam1=1

<h1>10秒比较</h1>
<cache expires-after="@TimeSpan.FromSeconds(10)">
    this will be cached in server memory. @DateTime.Now.ToString("hh:mm:ss tt")
</cache>
<br/>
<span>
    this will be cached in server memory. @DateTime.Now.ToString("hh:mm:ss tt")
</span>



<h1>3个属性比较</h1>
<!--expires-on 过期的时间点-->
<cache expires-on="@DateTime.Today.AddHours(15)">
    this will be cached in server memory. @DateTime.Now.ToString("hh:mm:ss tt")
</cache>
<br/>
<!--expires-after 最常用的一个，它表示缓存内容过期的时间段（timespan）-->
<cache expires-after="@TimeSpan.FromSeconds(10)">
    this will be cached in server memory. @DateTime.Now.ToString("hh:mm:ss tt")
</cache>
<br/>
<!--expires-sliding 每次内容被请求后缓存被延长的时间（timespan）-->
<cache  expires-sliding="@TimeSpan.FromSeconds(10)">
    this will be cached in server memory. @DateTime.Now.ToString("hh:mm:ss tt")
</cache>



<h1>vary-by</h1>
<h2>vary-by-query</h2>
<!-- /home/cache?queryParam1=1 -->
<cache expires-after="@TimeSpan.FromSeconds(10)" vary-by-query="queryParam1">
    缓存10秒
    this will be cached in server memory. @DateTime.Now.ToString("hh:mm:ss tt")
</cache>

<h2>vary-by-route</h2>
<div>接受路由参数名称的逗号分隔列表，用于在路由数据参数值发生更改时触发缓存刷新。</div>

<h2>vary-by-cookie</h2>
<div>根据存储在cookie中的某一个值来创建唯一的缓存，逗号分隔cookie名称列表</div>


<h2>vary-by-header</h2>
<div>基于请求头的某一个参数来创建唯一的缓存，只需要单个请求头名称</div>


<h2>vary-by-user</h2>
<div>指定当已登录用户（或上下文主体）发生更改时是否应重置缓存.</div>

分布式 Cache

为什么我们应该使用分布式缓存？

支持更高的缩放比例（与内存缓存相比）
使用分布式缓存将缓存内存迁移到外部进程
我们在所有的Web服务器上得到一致的数据（用户总是得到相同的结果，无论他们访问到哪台Web服务器）
缓存的数据在服务器重新启动和部署时不会丢失
我们可以停止或添加Web服务器，不会丢失缓存的数据
现在我们谈谈我们前面提到的分布式缓存Tag Helper。

分布式缓存Tag Helper的行为与缓存Tag helper几乎相同。对<cache> Tag Helper提供每一个属性也可用于<distributed-cache> Tag Helper。

但是，Distributed Cache TagHelper的区别在于它使我们能够注入和使用外部缓存管理器，而不是使用默认的内存缓存管理器。

如果您需要将缓存的HTML内容存储在用SQL Server、Redis等分布式缓存中，那么您需要 Tag Helper。

ASP.NET Core MVC提供两个缓存管理器的实现，分别是SQL Server和Redis。

另一个分布式缓存需要注意的是，它需要一个name属性。

参考：http://www.cnblogs.com/tdfblog/p/caching-taghelpers-in-asp-net-core-mvc.html
https://docs.microsoft.com/zh-cn/aspnet/core/mvc/views/tag-helpers/built-in/distributed-cache-tag-helper?view=aspnetcore-2.1

表单

Form

<form asp-controller="Demo" asp-action="Register" method="post">
    <!-- Input and Submit elements -->
</form>

生成的HTML

<form method="post" action="/Demo/Register">
    <!-- Input and Submit elements -->
    <input name="__RequestVerificationToken" type="hidden" value="<removed for brevity>" />
</form>

请注意在HTTP Post操作方式中，RequestVerificationToken 与内置的[ValidateAntiForgeryToken]属性一起工作，同时，该请求方法会被标记为post方式。

Form Tag Helper的还提供了 asp-route-{ParameterName} 属性，其中参数名称为被添加到路由的值；并且还提供了@Html.BeginForm和@Html.BeginRouteForm另一种清晰的替代方式。

Input

这一个很简单，它是@Html.EditorFor(m => m.Name)的替代方式。

Lable

这一个也很简单，它是@Html.LabelFor(m => m.Name)的替代方式。
它与输入框Tag Helper配合使用：

 <input asp-for="Name" />
    <label asp-for="Name" />

定义两个类

public class AddressViewModel
{
	public string AddressLine1 { get; set; }
}

public class RegisterAddressViewModel
{
	[Required]
	[MinLength(50)]
	[MaxLength(200)]
	public string Description { get; set; }
		
	[Display(Name = "Register Email")]
	public string Email { get; set; }

	[DataType(DataType.Password)]
	public string Password { get; set; }

	public AddressViewModel Address { get; set; }
}

TextArea

<textarea asp-for="Description"></textarea><br />

生成

<textarea data-val="true" data-val-maxlength="The field Description must be a string or array type with a maximum length of '200'." data-val-maxlength-max="200" data-val-minlength="The field Description must be a string or array type with a minimum length of '50'." data-val-minlength-min="50" data-val-required="The Description field is required." id="Description" name="Description"></textarea>

Validation

我们使用Validation Tag Helper为我们的视图模型的属性显示验证消息，使用方式也很简单：

<span asp-validation-for="Name"></span>

生成

<span class="field-validation-valid" data-valmsg-for="Name" data-valmsg-replace="true"></span>

综合例子

@model RegisterAddressViewModel

<form asp-controller="Demo" asp-action="RegisterAddress" method="post">
    <label asp-for="Email"></label> :  <input asp-for="Email" /> <br />
    <label asp-for="Password"></label>: <input asp-for="Password" /> <br /><span asp-validation-for="Password"></span><br />
    <label asp-for="Address"></label>: <input asp-for="Address.AddressLine1" /><br />
    <textarea asp-for="Description"></textarea><br />
    <button type="submit">Register</button>
</form>

生成

<form method="post" action="/Demo/RegisterAddress" novalidate="novalidate">
    <label for="Email">Register Email</label> :  <input type="text" id="Email" name="Email" value=""> <br>
    <label for="Password">Password</label>: <input type="password" data-val="true" data-val-required="The Password field is required." id="Password" name="Password"> <br><span class="field-validation-valid" data-valmsg-for="Password" data-valmsg-replace="true"></span><br>
    <label for="Address">Address</label>: <input type="text" id="Address_AddressLine1" name="Address.AddressLine1" value=""><br>
    <textarea data-val="true" data-val-maxlength="The field Description must be a string or array type with a maximum length of '200'." data-val-maxlength-max="200" data-val-minlength="The field Description must be a string or array type with a minimum length of '50'." data-val-minlength-min="50" data-val-required="The Description field is required." id="Description" name="Description"></textarea><br>

    <button type="submit">Register</button>
<input name="__RequestVerificationToken" type="hidden" value="CfDJ8E8SUbZpCkNIprGBJ28vOqxP8Qqc_XkuoKoGsVS2b7N-WBCS68EFGRFQBcZRARdNip0nQw45i8zy4f5XYlA1WGbaeEvYY7GDPwtM0bbjUZSHEAHEptxRzGMSXzIzyBnKkQLtvZkdjBhF5zX6VoBke38"></form>

自定义 Tag Helpers

通过创建自定义Tag Helpers，我们可以扩展现有元素或创建我们自己的元素。
Tag Helper是实现ITagHelper接口类的统称。MVC为我们提供了该接口的抽象类TagHelper，它位于 Microsoft.AspNetCore.Razor.Runtime 程序集中。因此，我们可以直接从TagHelper类继承，我们主要需要实现以下方法：

  public virtual void Process(TagHelperContext context, TagHelperOutput output);

  public virtual Task ProcessAsync(TagHelperContext context, TagHelperOutput output);

Process方法是具体的逻辑实现。它需要传递 Tag Helper上下文的实例和Tag Helper输出（我们可以用它来读取和更改Tag Helper范围内的实际内容）

简单示例

我们创建自己的Tag Helper。假设我们将使用<simple> </simple>Tag Helper，其中的内容将是粗体。

我们将要创建一个名为CustomTagHelpers的新项目。因此，程序集名称也将是 CustomTagHelpers。

首先，我们创建一个新的Tag Helper。使用Visual Studio，我们可以这样操作添加 - > 新建项 - > Web - > Razor 标记帮助器。

这是默认生成的代码：

    public class SimpleTagHelper : TagHelper
    {
        public override void Process(TagHelperContext context, TagHelperOutput output)
        {
            output.TagName = "strong";          
        }
    }

为了能够在我们的视图中使用新创建的Tag Helper，我们必须在 ViewImports.cshtml 文件中添加下面这一行：

@using IdentityDemo2
@using IdentityDemo2.Models
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@addTagHelper "*, IdentityDemo2"

以上代码我们使用了通配符表明所有的 tag helper 都将在我们的程序集中启用。
@addTagHelper 之后的第一个字符串指明了要加载的 tag helper（我们使用 "*" 代表所有 tag helper ），
第二个字符串 “IdentityDemo2” 指明了此 tag helper 所在的程序集。除此之外要注意的是，
使用通配符的第二行，引入了 ASP.NET Core MVC 的 tag helper（这些辅助类在 Tag Helpers 介绍中已经讨论过）。
是 @addTagHelper 命令使 tag helper 在 Razor 视图中起作用的。你还可以提供如下所示的 tag helper 的全名（FQN）：

<div>
    <Simple>2.simple.你是天边的亿朵元</Simple>
</div>

我们将在Visual Studio中看到这个simple 的标签已经变成紫色，并且被识别为Tag Helper。如果我们运行应用程序，我们将以粗体显示此文本。

如果我们查看HTML输出，我们可以看到simple 标签被strong所替代：

<div>
    <strong>2.simple你是天边的亿朵元</strong>
</div>

改变属性，构建一个 Email 标签

  public class EmailTagHelper : TagHelper
    {
        private const string EmailDomain = "contoso.com";

        // Can be passed via <email mail-to="..." />. 
        // Pascal case gets translated into lower-kebab-case.
        public string MailTo { get; set; }

        public override void Process(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);
        }
    }

例如：

<email>Support</email>

生成

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

资料：

Sweet-Tang,ASP.NET Core MVC – Tag Helpers 介绍
Form tagHelper，窗体中使用TagHelpers
作者：Rick Anderson，翻译：张海龙(jiechen)，自定义辅助类标签 Email