ASP.NET Core应用程序9：使用内置的标签助手

  ASP.NET Core 提供了一组内置的标签助手，可以应用最常用的元素转换。使用了内置的标签助手，就不必像前一章一样自己创建自定义标签助手。
  本章描述了基本的内置标签助手，并解释了它们是如何用于转换锚、链接、脚本和图像元素的。还解释了如何缓存内容部分以及如何根据应用程序的环境呈现内容。

1 准备工作

  本章继续使用前一章中的项目。

  注释Startup.cs中注释掉前一章标签组件助手语句。

//services.AddTransient<ITagHelperComponent, TimeTagHelperComponent>();
//services.AddTransient<ITagHelperComponent, TableFooterTagHelperComponent>();

  Home 文件夹中更新_RowPartial.cshtml部分视图。

@model Product
<tr>
    <td>@Model.Name</td>
    <td>@Model.Price.ToString("c")</td>
    <td>@Model.CategoryId</td>
    <td>@Model.SupplierId</td>
</tr>

  在 Home 控制器的 List 视图中呈现的 table 内定义额外的列。

@model IEnumerable<Product>
@{
    Layout = "_SimpleLayout";
}

<h6 class="bg-secondary text-white text-center m-2 p-2">Products</h6>
<div class="m-2">
    <table class="table table-sm table-striped table-bordered">
        <thead>
            <tr>
                <th>Name</th>
                <th>Price</th>
                <th>Category</th>
                <th>Supplier</th>
            </tr>
        </thead>
        <tbody>
            @foreach (Product p in Model)
            {
                <partial name="_RowPartial" model="p" />
            }
        </tbody>
    </table>
</div>

  添加图像文件。创建 wwwroot/images 文件夹，并添加了一个名为 city.png 的图像文件。本章中的一些示例演示了使用 JavaScript 文件的标签助手支持，对此使用jQuery 包。libman install jquery@3.4.1 -d wwwroot/lib/jquery。

  使用浏览器请求 http://localhost:5000/Home/list ，这会显示一个产品列表。

2 启用内置的标签助手

  内置的标签助手都在 Microsoft.AspNetCore.Mvc.TagHelpers 名称空间中定义，启用它的方法是向单个视图或页面添加 @addTagHelper 指令，或者向视图导入文件添加该指令。

  下面是 Views 文件夹中 _ViewImports.cshtml 文件的必需指令，它为控制器视图启用内置的标签助手。

@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers

3 改变锚元素

  元素是在应用程序中导航和向应用程序发送 GET 请求的基本工具。AnchorTagHelper 类用于转换元素的 href 属性，以便它们指向使用路由系统生成的 URL，即不需要硬编码的 URL，路由配置中的更改将自动反映在应用程序的锚元素中。

  以下描述了 AnchorTagHelper 类支持的属性，内置标签助手。

名称	描述
asp-action	此属性指定 URL 指向的操作方法
asp-controller	此属性指定URL指尚的控制器。如果省略此属性，则 URL 将指向呈现当前视图的控制页面
asp-page	此属性指定 URL 指向的 Razor Pages
asp-page-handler	此属性指定 Razor Pages 处理函数来处理请求
asp-fragment	此属性用于指定 URL 片段(出现在#字符之后)
asp-host	此属性指定 URL 指向的主机名称
asp-protocol	此属性指定 URL 使用的协议
asp-route	此属性指定用于生成 URL的路由名称
asp-route-*	名称以 asp-route 开头的属性用于为 URL 指定附加值，以便使用 asp-route-id 属性为路由系统提供 id 段的值
asp-all-route-data	此属性提供用于路由的值作为单个值，而非使用单个属性

  AnchorTagHelper 很容易在使用应用程序路由配置的元素中生成 URL。以下Views/Home 文件夹的 _RowPartial.cshtml 文件中添加了一个锚元素，它使用表中的属性创建一个 URL，该 URL 针对主控制器定义的另个操作。

@model Product

<tr>
    <td>@Model.Name</td>
    <td>@Model.Price.ToString("c")</td>
    <td>@Model.CategoryId</td>
    <td>@Model.SupplierId</td>
    <td>
        <a asp-action="index" asp-controller="home"
           asp-route-id="@Model.ProductId" class="btn btn-sm btn-info">
            Select
        </a>
    </td>
</tr>

  asp-action 和 asp-controller 属性指定操作方法的名称和定义它的控制器。段变量的值是使用 asp-route-[name] 属性定义的，这样，asp-route-id 属性为id 段变量提供一个值，该值用于为 asp-action 属性选择的操作方法提供一个参数。

  要查看锚元素转换，请使用浏览器请求 http:/localhost:5000/home/list 。

  如果检査 Select 锚元素，则每个 href 属性包括与之相关的 Product 对象的 Productld 值，如下所示:

<a class="btn btn-sm btn-info" href="/Home/index/3">Select</a>

  这种情况下，asp-route-id 属性提供的值意味着不能使用默认 URL，所以路由系统生成了 URL包括控制器和操作名称部分，以及一个用来提供操作方法参数的段。在这两种情况下，由于只指定了一个操作方法，所以由标签助手创建的 URL，将指向呈现视图的控制器。单击锚元素将发送个指向主控制器的 Index 方法的 HTTP GET 请求。

为 Razor Pages 使用锚元素
  asp-page 属性用于指定 Razor Pages 作为锚元素的 href 属性的目标。页面的路径以/字符为前缀，@page 指令定义的路由段值使用 asp-route-[name] 属性定义。如下代码添加了一个锚元素指向在 Pages/Suppliers 文件夹中定义的 List 页面，在 Views/Home 文件夹的 List.cshtml 文件中指向 Razor Pages。

<a asp-page="/suppliers/list" class="btn btn-secondary">Suppliers</a>

  使用浏览器请求 http://localhost:5000/home/list ，就会看到样式为按钮的锚元素。如果检查发到客户端的 HTML，会看到锚元素已转换，如下:

<a class="btn btn-secondary" href="/lists/suppliers">Suppliers</a>

  href 属性中使用的这个 URL 反映了@page 指令,该指令用于覆盖此页中的默认路由约定，单击该元素，浏览器将显示 Razor Pages。

4 使用 JavaScript 和 CSS 标签助手

  ASP.NET Core 提供了通过脚本和链接元素来管理 JavaScript 文件和 CSS 样式表的标签助手，这些标签助手功能强大且灵活。

4.1 管理 JavaScript 文件

  ScriptTagHelper 类是脚本元素的内置标签助手，可使用下表中描述的属性来管理视图中包含的 JavaScript 文件。
  脚本元素的内置标签助手属性：

名称	描述
asp-src-include	此属性用于指定包含在视图中的 JavaScript 文件
asp-src-exclude	此属性用于指定将从视图中排除的 JavaScript 文件
asp-append-version	此属性用于缓存破解，如“了解缓存破解”侧栏中所述
asp-fallback-src	此属性用于指定在内容传递网络出现问题时使用的回退JavaScript 文件
asp-fallback-src-include	此属性用于选择在出现内容传递网络问题时使用的JavaScript 文件
asp-fallback-src-exclude	此属性用于排除 JavaScript 文件，以便在出现内容传递网络问题时显示它们的用途
asp-fallback-test	此属性用于指定一个 JavaScript片段，该JavaScript片段用于确定 JavaScript 代码是否已从内容传递网络中正确加载

（1）选择 JavaScript 文件
  asp-src-include 属性用于通过 Globbing 模式，在视图中包含 JavaScript 文件。Globbing模式支持一组用于匹配文件的通配符，下表描述了最常见的 Globbing 模式。

模式	示例	描述
?	js/src?.js	此模式匹配除/之外的任何单个字符。该示例匹配js目录中包含的任何名称为src后跟任何字符和.js 的文件，例如 js/src1.js 和 js/srcX.js ，但不匹配 js/src123.js 或js/mydir/src1.js
*	js/*.js	此模式匹配除/之外的任意数量的字符。该示例匹配 js 目录中任何扩展名为js的文件，例如 js/src1.js 和 js/src123.js ，但不匹配js/mydir/src1.js
**	js/**/*.js	该模式匹配包括/在内的任意数量的字符。该示例匹配 js 目录或任何子目录中任何扩展名为.js的文件，例如/js/src1.js 和/js/mydir/src1.js

  Globbing 是确保视图包含应用程序需要的 JavaScript 文件的一种有用方法，即使文件的路径发生了变化。
使用 asp-src-include 属性来包含 wwwroot/lib/jquery 文件夹中的所有 JavaScript 文件，该文件夹是使用如下在 Views/Shared 文件夹的 _SimpleLayout.cshtml 中的命令安装的 jQuery 包的位置。

<script asp-src-include="lib/jquery/**/*.js"></script>

  在 wwwroot 文件夹评估模式,这里使用的模式对应于任何扩展名为.js 的文件，而不考虑它在wwwroot 文件夹的位置；这意味着添加到项目中的任何JavaScript 包都包含在发送给客户端的HTML 中。
  使用浏览器请求 http://localhost:5000/home/list ，并检査发送到浏览器的 HTML。布局中的单一脚本元素已经转换为每个 JavaScript 文件的 script 元素，如下所示:

<script src="/lib/jquery/core.js"></script>
<script src="/lib/jquery/jquery.js"></script>
<script src="/lib/jquery/jquery.min.js"></script>
<script sre="/lib/jquery/jquery.slim.js"></script>
<script src="/1ib/jquery/jquery.slim.min.js"></script>

（2）缩小 Globbing 模式
  任何应用程序都不需要上面的模式的选择的所有文件。许多包都包含多个JavaScript 文件，这些文件包含类似的内容，通常删除不太流行的特性以节省带宽。jQuery 包包括jQuery.slim,js 文件，该文件包含与jQuery.js 文件相同的代码，但没有处理异步 HTTP 请求和动画效果的特性(还有一个 core.js 文件，但它错误地包含在包中，应该忽略)。
  这些文件中的每一个都对应于 min.js 文件扩展名，它表示一个缩小的文件。“缩小”通过删除所有空格、重命名函数和变量以使用更短的名称，来减小 JavaScript 文件的大小。
  每个包只需要一个 JavaScript 文件，如果只需要缩小版本(大多数项目都是这样)，就可以限制Globbing 模式匹配的文件集，如下所示。

<script asp-src-include="lib/jquery**/*slim.min.js"></script>

  html响应如下：

<script src="/lib/jquery/jquery.slim.min.js"></script>

（3）不包括文件
  希望选择名称中包含特定术语(如 slim)的文件时，缩小 JavaScript 文件的模式将有所帮助。想要的文件没有这个术语时，例如想要缩小文件的完整版本时，它就没有帮助了。幸运的是，可使用 asp-src-exclude 属性从与 asp-src-include 属性匹配的列表中删除文件，如下所示。

<script asp-src-include="/lib/jquery/**/*.min.js"
        asp-src-exclude="**.slim.**">
</script>

  html响应如下：

<script sre"/lib/jquery/jquery.min.js"></seript>

（4）使用内容发布网络

<script src="https://cdnjs.cloudflare.com/ajax/libs/jguery/3.4.1/jquery.min.js
    asp-fallback-src="/lib/jquery/jquery.min.js'asp-fallback-test="window.jQuery">
</script>

  src 属性用于指定 CDN URL。asp-fallback-src 属性用于指定一个本地文件，如果 CDN 不能传递常规 src 属性指定的文件，就使用该文件。为了弄清楚CDN是否在工作，asp-fallback-test 属性用来定义一个 JavaScript片段，它将在浏览器中评估。如果片段计算为 false，将请求回退文件。

4.2 管理 CSS 样式表

  LinkTagHelper 类是链接元素的内置标签助手，用于管理视图中包含的 CSS 样式表。这个标签助手支持下表中描述的属性。
链接元素的内置标签助手属性：

名称	描述
asp-href-include	此属性用于为输出元素的 href属性选择文件
asp-href-exclude	此属性用于从输出元素的 href属性中排除文件
asp-append-version	此属性用于启用缓存破解
asp-fallback-href	此属性用于在 CDN 出现问题时指定一个回退文件
asp-fallback-href-include	此属性用于在出现 CDN 问题时选择要使用的文件
asp-fallback-href-exclude	此属性用于在存在CDN问题时从使用的文件集中排除文件
asp-fallback-href-test-class	此属性指定用于测试 CDN 的 CSS 类
asp-fallback-href-test-property	此属性指定用于测试 CDN 的 CSS 属性
asp-fallback-href-test-yalue	此属性指定用于测试 CDN 的 CSS 值

（1）选择样式表
  LinkTagHelper 与 ScriptTagHelper 共享许多特性，包括支持 Globbing 模式来选择或排除CS文件，这样它们就不必单独指定了。能够准确地选择 CSS 文件和选择 JavaScript 文件一样重要，因为样式表有常规版本和缩小版本，并且支持源映射。流行的 Bootstrap 包(本书一直使用它来议计 HTMI 元素的样式)包括其在 wwwroot/lib/twiter-bootstrap/css 文件夹中的 CSS 样式表。

  bootstrap.css 文件是常规样式表，bootstrap.min.css 文件是缩小版，bootstrap.css.map 文件是源映射。其他文件包含CSS特性的子集，以便在不使用这些特性的应用程序中节省带宽。
  以下在Views/Shared 文件夹的 _SimpleLayout.cshtml中，将布局中的常规链接元素替换为使用 asp-href-include 和 asp-href-exclude 属性的元素(删除了 jQuery 的脚本元素，它不再是必需的)。

<link asp-href-include="/lib/twitter-bootstrap/css/*.min.css"
    asp-href-exclude="**/*-reboot*,**/*-grid" rel="stylesheet" />

（2）使用内容发布网络

<link href="https://ednjs.clouflare.com/ajax/1ibs/twitter-bootstrap/4.3.1css/bootstrap.min.css"
    asp-fallback-href="/lib/twitter-bootstrap/css/bootstrap.min.css" rel="stylesheet"/>

  href 属性用于指定 CDN URL，这里使用 asp-fallback-href 属性来选择 CDN 不可用时要使用的文件。

5 处理图像元素

  ImageTagHelper 类通过 img 元素的 src 属性为图像提供缓存破解，允许应用程序利用缓存,同时确保对图像的修改能够立即反映出来。ImageTagHelper 类在定义 asp-append-version 属性的 img 元素中操作，此属性用于启用缓存破解。

  在 Views/Shared 文件夹的 _SimpleLayout.cshtml中，向城市天际线图像的共享布局中添加了一个 img 元素。

<img src="/images/city.png" asp-append-version="true" class="m-2" />

  使用浏览器请求 http://localhost:5000/home/list ，査 HTML, 响应，会看到用于请求图像文件的 URL,包含一个版本校验和。

<img src="/images/city.png?v-KaMNDSZFAJufReRDpKhOK_IIPNc7E" class="m-2">

6 使用数据缓存

  CacheTagHelper 类允许缓存内容片段，以加快视图或页面的呈现。缓存的内容使用 cache元素表示，cache 元素使用下表所示的属性配置。
  缓存元素的内置标签助手属性：

名称	描述
enabled	此 bool属性用于控制是否缓存被缓存元素的内容。省略此属性将启用缓存
expires-on	此属性用于指定缓存内容过期的绝对时间，表示为DateTime值
expires-after	此属性用于指定缓存内容的相对过期时间，表示为TimeSpan 值
expires-sliding	此属性用于指定缓存内容过期的时间段，即自上次使用它以来的时间段，并表示为TimeSpan 值
vly-by-header	此属性用于指定请求头的名称，该请求头用于管理缓存内容的不同版本
vary-by-query	此属性用于指定查询字符串键的名称，该键用于管理缓存内容的不同版本
vary-by-route	此属性用于指定一个路由变量的名称，该变量用于管理缓存内容的不同版本
vary-by-cookie	此属性用于指定 cookie 的名称，该 cookie 用于管理缓存内容的不同版本
vary-by-user	此 bool属性用于指定是否使用经过身份验证的用户的用户名来管理缓存内容的不同版本
vary-by- content	计算此属性，以提供一个用于管理不同版本内容的密钥
priority	此属性用于指定一个相对优先级，当内存缓存耗尽空间并清除未过期的缓存内容时，将考虑该优先级

  以下用包含时间戳的内容替换了上一节中的 img 元素，在 Views/Shared 文件夹的 _SimpleLayout.cshtml 文件中缓存内容。

<h6 class="bg-primary text-white m-2 p-2">
    Uncached timestamp:@DateTime.Now.ToLongTimeString()
</h6>
<cache>
    <h6 class="bg-primary text-white m-2 p-2">
        Cached timestamp: @DateTime.Now.ToLongTimeString()
    </h6>
</cache>

  cache 元素用于表示应该缓存的内容区域，该内容区域已应用于包含时间戳的 h6 元素之一。使用浏览器请求 http://localhost:5000/home/list ，那么两个时间戳将是相同的。重新加载浏览器，会看到缓存的内容用于其中一个 h6 元素，时间戳没有变化。

6.1 设置缓存到期时间

  expires-* 属性允许指定缓存内容何时过期，可以表示为绝对时间或相对于当前时间的时间也可以指定缓存内容不被请求的持续时间。在Views/Shared 文件夹的_SimpleLayout.cshtml 文件中设置缓存过期时间，使用了 expires-after 属性来指。应该将内容缓存 15 秒。

<cache expires-after="@TimeSpan.FromSeconds(15)">
    <h6 class="bg-primary text-white m-2 p-2">
        Cached timestamp: @DateTime.Now.ToLongTimeString()
    </h6>
</cache>

  使用浏览器请求 http://localhost:5000/home/list ，然后重新加载页面。15 秒后，缓存的内容过期，并创建一个新的内容部分。

6.2 设置固定的过期点

  可以使用 expireson-on 属性指定缓存内容的固定过期时间，该属性接收一个 DateTime 值。

<cache expires-on="@DateTime.Parse("2030-01-01")">

6.3 设置最后使用的有效期

  expires-sliding 属性用于指定一个期限，如果内容还没有从缓存中检索，则在该期限之后内容将过期。以下指定了滑动到期时间为10秒。

<cache expires-sliding="@TimeSpan.FromSeconds(10)">

6.4 使用缓存的变化

  默认情况下，所有请求接收相同的缓存内容。CacheTagHelper 类可以维护缓存内容的不同版本，并使用它们来满足不同类型的 HTTP 请求，使用名称以 vary-by 开头的属性指定。如下显示了使用 vary-by-route 属性根据路由系统匹配的操作值来创建缓存变量。

<cache expires-sliding="@TimeSpan.FromSeconds(10)" vary-by-route="action">

  如果使用两个浏览器选项卡来请求 http:/localhost:5000/home/index 和 http://localhost:5000/home/list 会看到每个窗口接收自己的缓存内容和过期时间，因为每个请求生成不同的操作路由值。

7 使用宿主环境标签助手

  EnvironmentTagHelper 类应用于自定义环境元素，并确定基于托管环境发送到浏览器的 HTML 中是否包含某个内容区域。environment 元素依赖于 names 属性，此属性用于指定以逗号分隔的主机环境名称列表，其中包含在 environment 元素中的内容将包含在发送给客户端的 HTML中。
  以下在 Views/Shared 文件夹的 _SimpleLayout.cshtml 文件中使用环境元素，包括视图中用于开发和生产托管环境的不同内容。

<environment names="development">
    <h2 class="bg-info text-white m-2 p-2">This is Development</h2>
</environment>
<environment names="production">
    <h2 class="bg-danger text-white m-2 p-2">This is Production</h2>
</environment>

  environment 元素检査当前宿主环境名，并包含它所包含的内容或省略。