Menandai Pembantu di ASP.NET Core

Artikel
11/30/2023

Apa itu Pembantu Tag

Pembantu Tag memungkinkan kode sisi server untuk berpartisipasi dalam membuat dan merender elemen HTML dalam Razor file. Misalnya, bawaan ImageTagHelper dapat menambahkan nomor versi ke nama gambar. Setiap kali gambar berubah, server menghasilkan versi unik baru untuk gambar, sehingga klien dijamin mendapatkan gambar saat ini (alih-alih gambar cache kedaluarsa). Ada banyak Pembantu Tag bawaan untuk tugas umum - seperti membuat formulir, tautan, memuat aset, dan banyak lagi - dan bahkan lebih tersedia di repositori GitHub publik dan sebagai paket NuGet. Pembantu Tag ditulis dalam C#, dan mereka menargetkan elemen HTML berdasarkan nama elemen, nama atribut, atau tag induk. Misalnya, bawaan LabelTagHelper dapat menargetkan elemen HTML <label> saat LabelTagHelper atribut diterapkan. Jika Anda terbiasa dengan Pembantu HTML, Penolong Tag mengurangi transisi eksplisit antara HTML dan C# dalam Razor tampilan. Dalam banyak kasus, Pembantu HTML menyediakan pendekatan alternatif untuk Pembantu Tag tertentu, tetapi penting untuk mengenali bahwa Pembantu Tag tidak mengganti Pembantu HTML dan tidak ada Pembantu Tag untuk setiap Pembantu HTML. Pembantu Tag dibandingkan dengan Pembantu HTML menjelaskan perbedaan secara lebih rinci.

Pembantu Tag tidak didukung dalam Razor komponen. Untuk informasi selengkapnya, lihat komponen ASP.NET CoreRazor.

Apa yang disediakan Oleh Pembantu Tag

Pengalaman pengembangan yang ramah HTML

Untuk sebagian besar, Razor markup menggunakan Pembantu Tag terlihat seperti HTML standar. Desainer front-end yang berkonversan dengan HTML/CSS/JavaScript dapat mengedit Razor tanpa mempelajari sintaks C# Razor .

Lingkungan IntelliSense yang kaya untuk membuat HTML dan Razor markup

Ini sangat kontras dengan Pembantu HTML, pendekatan sebelumnya untuk pembuatan markup sisi server dalam Razor tampilan. Pembantu Tag dibandingkan dengan Pembantu HTML menjelaskan perbedaan secara lebih rinci. Dukungan IntelliSense untuk Pembantu Tag menjelaskan lingkungan IntelliSense. Bahkan pengembang yang berpengalaman dengan Razor sintaks C# lebih produktif menggunakan Pembantu Tag daripada menulis markup C# Razor .

Cara untuk membuat Anda lebih produktif dan dapat menghasilkan kode yang lebih kuat, andal, dan dapat dipertahankan menggunakan informasi yang hanya tersedia di server

Misalnya, secara historis mantra pada memperbarui gambar adalah mengubah nama gambar saat Anda mengubah gambar. Gambar harus di-cache secara agresif karena alasan performa, dan kecuali Anda mengubah nama gambar, Anda berisiko klien mendapatkan salinan kedaluarsa. Secara historis, setelah gambar diedit, nama harus diubah dan setiap referensi ke gambar di aplikasi web perlu diperbarui. Tidak hanya ini sangat intensif tenaga kerja, ini juga rawan kesalahan (Anda bisa melewatkan referensi, secara tidak sengaja memasukkan string yang salah, dll.) Bawaan ImageTagHelper dapat melakukan ini untuk Anda secara otomatis. ImageTagHelper dapat menambahkan nomor versi ke nama gambar, jadi setiap kali gambar berubah, server secara otomatis menghasilkan versi unik baru untuk gambar. Klien dijamin mendapatkan gambar saat ini. Ketahanan dan penghematan tenaga kerja ini pada dasarnya gratis dengan menggunakan ImageTagHelper.

Sebagian besar Pembantu Tag bawaan menargetkan elemen HTML standar dan menyediakan atribut sisi server untuk elemen tersebut. Misalnya, elemen yang <input> digunakan dalam banyak tampilan di folder Tampilan/Akun berisi asp-for atribut . Atribut ini mengekstrak nama properti model yang ditentukan ke dalam HTML yang dirender. Razor Pertimbangkan tampilan dengan model berikut:

public class Movie
{
    public int ID { get; set; }
    public string Title { get; set; }
    public DateTime ReleaseDate { get; set; }
    public string Genre { get; set; }
    public decimal Price { get; set; }
}

Markup berikut Razor :

<label asp-for="Movie.Title"></label>

Menghasilkan HTML berikut:

<label for="Movie_Title">Title</label>

Atribut asp-for disediakan oleh For properti di LabelTagHelper. Lihat Pembantu Tag Penulis untuk informasi selengkapnya.

Mengelola cakupan Pembantu Tag

Cakupan Pembantu @addTagHelperTag dikontrol oleh kombinasi , @removeTagHelper, dan karakter penolakan "!".

`@addTagHelper` membuat Bantuan Tag tersedia

Jika Anda membuat aplikasi web ASP.NET Core baru bernama AuthoringTagHelpers, file berikut Views/_ViewImports.cshtml akan ditambahkan ke proyek Anda:

@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@addTagHelper *, AuthoringTagHelpers

Arahan @addTagHelper membuat Pembantu Tag tersedia untuk tampilan. Dalam hal ini, file tampilan adalah Pages/_ViewImports.cshtml, yang secara default diwarisi oleh semua file di folder Halaman dan subfolder; membuat Pembantu Tag tersedia. Kode di atas menggunakan sintaks kartubebas ("*") untuk menentukan bahwa semua Pembantu Tag dalam rakitan yang ditentukan (Microsoft.AspNetCore.Mvc.TagHelpers) akan tersedia untuk setiap file tampilan di direktori tampilan atau subdirektori. Parameter pertama setelah @addTagHelper menentukan Pembantu Tag yang akan dimuat (kami menggunakan "*" untuk semua Pembantu Tag), dan parameter kedua "Microsoft.AspNetCore.Mvc.TagHelpers" menentukan perakitan yang berisi Pembantu Tag. Microsoft.AspNetCore.Mvc.TagHelpers adalah perakitan untuk Pembantu Tag Inti ASP.NET bawaan.

Untuk mengekspos semua Pembantu Tag dalam proyek ini (yang membuat rakitan bernama AuthoringTagHelpers), Anda akan menggunakan hal berikut:

@using AuthoringTagHelpers
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@addTagHelper *, AuthoringTagHelpers

Jika proyek Anda berisi EmailTagHelper dengan namespace default (AuthoringTagHelpers.TagHelpers.EmailTagHelper), Anda dapat memberikan nama yang sepenuhnya memenuhi syarat (FQN) dari Pembantu Tag:

@using AuthoringTagHelpers
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@addTagHelper AuthoringTagHelpers.TagHelpers.EmailTagHelper, AuthoringTagHelpers

Untuk menambahkan Pembantu Tag ke tampilan menggunakan FQN, Anda terlebih dahulu menambahkan FQN (AuthoringTagHelpers.TagHelpers.EmailTagHelper), lalu nama rakitan (AuthoringTagHelpers). Sebagian besar pengembang lebih suka menggunakan sintaks kartubebas "*". Sintaks kartubebas memungkinkan Anda memasukkan karakter kartubebas "*" sebagai akhiran dalam FQN. Misalnya, salah satu arahan berikut akan membawa EmailTagHelper:

@addTagHelper AuthoringTagHelpers.TagHelpers.E*, AuthoringTagHelpers
@addTagHelper AuthoringTagHelpers.TagHelpers.Email*, AuthoringTagHelpers

Seperti disebutkan sebelumnya, menambahkan @addTagHelper direktif ke Views/_ViewImports.cshtml file membuat Pembantu Tag tersedia untuk semua file tampilan di direktori Tampilan dan subdirektori. Anda dapat menggunakan direktif @addTagHelper dalam file tampilan tertentu jika Anda ingin ikut serta mengekspos Pembantu Tag hanya untuk tampilan tersebut.

`@removeTagHelper` menghapus Pembantu Tag

memiliki dua parameter yang sama dengan @addTagHelper, dan menghapus Pembantu @removeTagHelper Tag yang sebelumnya ditambahkan. Misalnya, @removeTagHelper diterapkan ke tampilan tertentu akan menghapus Pembantu Tag yang ditentukan dari tampilan. Menggunakan @removeTagHelper dalam Views/Folder/_ViewImports.cshtml file menghapus Pembantu Tag yang ditentukan dari semua tampilan di Folder.

Mengontrol cakupan Pembantu `_ViewImports.cshtml` Tag dengan file

Anda dapat menambahkan _ViewImports.cshtml ke folder tampilan apa pun, dan mesin tampilan menerapkan arahan dari file dan file tersebut Views/_ViewImports.cshtml . Jika Anda menambahkan file kosong Views/Home/_ViewImports.cshtml untuk Home tampilan, tidak akan ada perubahan karena _ViewImports.cshtml file bersifat aditif. Arahan apa pun @addTagHelper yang Anda tambahkan ke Views/Home/_ViewImports.cshtml file (yang tidak ada dalam file default Views/_ViewImports.cshtml ) akan mengekspos Pembantu Tag tersebut Home untuk dilihat hanya di folder.

Memilih keluar dari elemen individual

Anda dapat menonaktifkan Pembantu Tag di tingkat elemen dengan karakter penolakan Pembantu Tag ("!"). Misalnya, Email validasi dinonaktifkan di <span> dengan karakter penolakan Pembantu Tag:

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

Anda harus menerapkan karakter penolakan Pembantu Tag ke tag pembuka dan penutup. (Editor Visual Studio secara otomatis menambahkan karakter penolakan ke tag penutup saat Anda menambahkannya ke tag pembuka). Setelah Anda menambahkan karakter opt-out, elemen dan atribut Tag Helper tidak lagi ditampilkan dalam font yang khas.

Menggunakan `@tagHelperPrefix` untuk membuat penggunaan Tag Helper menjadi eksplisit

Direktif @tagHelperPrefix memungkinkan Anda menentukan string awalan tag untuk mengaktifkan dukungan Pembantu Tag dan membuat penggunaan Pembantu Tag menjadi eksplisit. Misalnya, Anda dapat menambahkan markup berikut ke Views/_ViewImports.cshtml file:

@tagHelperPrefix th:

Dalam gambar kode di bawah ini, awalan Pembantu Tag diatur ke th:, jadi hanya elemen yang menggunakan awalan th: yang mendukung Pembantu Tag (elemen yang mendukung Pembantu Tag memiliki font yang khas). Elemen <label> dan <input> memiliki awalan Tag Helper dan diaktifkan Tag Helper, sementara <span> elemen tidak.

Razor markup with Tag Helper prefix set to

Aturan hierarki yang sama yang berlaku untuk juga berlaku untuk @addTagHelper@tagHelperPrefix.

Pembantu Tag penutupan mandiri

Banyak Pembantu Tag tidak dapat digunakan sebagai tag penutupan mandiri. Beberapa Pembantu Tag dirancang untuk menjadi tag penutupan mandiri. Menggunakan Pembantu Tag yang tidak dirancang untuk menutup diri menekan output yang dirender. Menutup sendiri Tag Helper menghasilkan tag penutupan mandiri dalam output yang dirender. Untuk informasi selengkapnya, lihat catatan ini di Penulisan Pembantu Tag.

C# dalam atribut/deklarasi Pembantu Tag

Pembantu Tag tidak mengizinkan C# di area deklarasi atribut atau tag elemen. Misalnya, kode berikut tidak valid:

<input asp-for="LastName"  
       @(Model?.LicenseId == null ? "disabled" : string.Empty) />

Kode sebelumnya dapat ditulis sebagai:

<input asp-for="LastName" 
       disabled="@(Model?.LicenseId == null)" />

Biasanya, @ operator menyisipkan representasi tekstual ekspresi ke dalam markup HTML yang dirender. Namun, ketika ekspresi mengevaluasi ke logis false, kerangka kerja akan menghapus atribut sebagai gantinya. Dalam contoh sebelumnya, disabled atribut diatur ke true jika atau ModelLicenseId adalah null.

Penginisialisasi pembantu tag

Meskipun atribut dapat digunakan untuk mengonfigurasi instans individu pembantu tag, ITagHelperInitializer<TTagHelper> dapat digunakan untuk mengonfigurasi semua instans pembantu tag dari jenis tertentu. Pertimbangkan contoh penginisialisasi pembantu tag berikut yang mengonfigurasi asp-append-version atribut atau AppendVersion properti untuk semua instans ScriptTagHelper dalam aplikasi:

public class AppendVersionTagHelperInitializer : ITagHelperInitializer<ScriptTagHelper>
{
    public void Initialize(ScriptTagHelper helper, ViewContext context)
    {
        helper.AppendVersion = true;
    }
}

Untuk menggunakan penginisialisasi, konfigurasikan dengan mendaftarkannya sebagai bagian dari startup aplikasi:

builder.Services.AddSingleton
    <ITagHelperInitializer<ScriptTagHelper>, AppendVersionTagHelperInitializer>();

Tag Helper pembuatan versi otomatis di luar wwwroot

Agar Pembantu Tag menghasilkan versi untuk file statis di luar wwwroot, lihat Menyajikan file dari beberapa lokasi

Dukungan IntelliSense untuk Pembantu Tag

Pertimbangkan untuk menulis elemen HTML <label> . Segera setelah Anda masuk <l di editor Visual Studio, IntelliSense menampilkan elemen yang cocok:

After typing

Anda tidak hanya mendapatkan bantuan HTML, tetapi juga ikon (simbol "@" dengan "<>" di bawahnya).

The

Ikon mengidentifikasi elemen sebagai yang ditargetkan oleh Pembantu Tag. Elemen HTML murni (seperti fieldset) menampilkan ikon "<>".

Tag HTML <label> murni menampilkan tag HTML (dengan tema warna Visual Studio default) dalam font coklat, atribut berwarna merah, dan nilai atribut berwarna biru.

Example

Setelah Anda memasukkan <label, IntelliSense mencantumkan atribut HTML/CSS yang tersedia dan atribut tag yang ditargetkan Pembantu:

The user has typed an opening bracket and the HTML element name

Penyelesaian pernyataan IntelliSense memungkinkan Anda memasukkan kunci tab untuk menyelesaikan pernyataan dengan nilai yang dipilih:

The user has typed an opening bracket, the HTML element name

Segera setelah atribut Tag Helper dimasukkan, font tag dan atribut berubah. Menggunakan tema warna Visual Studio "Biru" atau "Terang" default, font berwarna ungu tebal. Jika Anda menggunakan tema "Gelap" font tebal. Gambar dalam dokumen ini diambil menggunakan tema default.

The user selected

Anda dapat memasukkan pintasan Visual Studio CompleteWord (Ctrl +spacebar adalah default) di dalam tanda kutip ganda (""), dan Anda sekarang berada di C#, sama seperti Anda berada di kelas C#. IntelliSense menampilkan semua metode dan properti pada model halaman. Metode dan properti tersedia karena jenis properti adalah ModelExpression. Pada gambar di bawah ini, saya mengedit Register tampilan, sehingga RegisterViewModel tersedia.

The user types

IntelliSense mencantumkan properti dan metode yang tersedia untuk model di halaman. Lingkungan IntelliSense yang kaya membantu Anda memilih kelas CSS:

The user types

Pembantu Tag dibandingkan dengan Pembantu HTML

Tag Helper melampirkan ke elemen HTML dalam Razor tampilan, sementara Pembantu HTML dipanggil sebagai metode yang diselingi dengan HTML dalam Razor tampilan. Pertimbangkan markup berikut Razor , yang membuat label HTML dengan "keterangan" kelas CSS:

@Html.Label("FirstName", "First Name:", new {@class="caption"})

Simbol at (@) memberi tahu Razor ini adalah awal kode. Dua parameter berikutnya ("FirstName" dan "First Name:") adalah string, sehingga IntelliSense tidak dapat membantu. Argumen terakhir:

new {@class="caption"}

Adalah objek anonim yang digunakan untuk mewakili atribut. Karena class adalah kata kunci yang dipesan dalam C#, Anda menggunakan @ simbol untuk memaksa C# menafsirkan @class= sebagai simbol (nama properti). Bagi desainer front-end (seseorang yang terbiasa dengan HTML/CSS/JavaScript dan teknologi klien lainnya tetapi tidak terbiasa dengan C# dan Razor), sebagian besar lini adalah asing. Seluruh baris harus ditulis tanpa bantuan dari IntelliSense.

LabelTagHelperMenggunakan , markup yang sama dapat ditulis sebagai:

<label class="caption" asp-for="FirstName"></label>

Dengan versi Tag Helper, segera setelah Anda masuk <l di editor Visual Studio, IntelliSense menampilkan elemen yang cocok:

The user types

IntelliSense membantu Anda menulis seluruh baris.

Gambar kode berikut menunjukkan bagian Formulir dari tampilan yang Views/Account/Register.cshtmlRazor dihasilkan dari templat MVC ASP.NET 4.5.x yang disertakan dengan Visual Studio.

Razor markup for the form portion of the Register Razor view for ASP.NET 4.5 MVC project template

Editor Visual Studio menampilkan kode C# dengan latar belakang abu-abu. Misalnya, Pembantu AntiForgeryToken HTML:

@Html.AntiForgeryToken()

ditampilkan dengan latar belakang abu-abu. Sebagian besar markup dalam tampilan Daftar adalah C#. Bandingkan dengan pendekatan yang setara menggunakan Pembantu Tag:

Razor markup with Tag Helpers for the form portion of the Register Razor view for an ASP.NET Core project template

Markup jauh lebih bersih dan lebih mudah dibaca, diedit, dan dikelola daripada pendekatan Pembantu HTML. Kode C# dikurangi menjadi minimum yang perlu diketahui server. Editor Visual Studio menampilkan markup yang ditargetkan oleh Pembantu Tag dalam font yang khas.

Pertimbangkan grup Email:

<div class="form-group">
    <label asp-for="Email" class="col-md-2 control-label"></label>
    <div class="col-md-10">
        <input asp-for="Email" class="form-control" />
        <span asp-validation-for="Email" class="text-danger"></span>
    </div>
</div>

Masing-masing atribut "asp-" memiliki nilai "Email", tetapi "Email" bukan string. Dalam konteks ini, "Email" adalah properti ekspresi model C# untuk RegisterViewModel.

Editor Visual Studio membantu Anda menulis semua markup dalam pendekatan Tag Helper formulir register, sementara Visual Studio tidak menyediakan bantuan untuk sebagian besar kode dalam pendekatan Pembantu HTML. Dukungan IntelliSense untuk Pembantu Tag masuk ke detail tentang bekerja dengan Pembantu Tag di editor Visual Studio.

Pembantu Tag dibandingkan dengan Kontrol Server Web

Pembantu Tag tidak memiliki elemen yang terkait dengannya; mereka hanya berpartisipasi dalam penyajian elemen dan konten. ASP.NET Kontrol Server Web dideklarasikan dan dipanggil pada halaman.
ASP.NET Kontrol Server Web memiliki siklus hidup non-sepele yang dapat menyulitkan pengembangan dan penelusuran kesalahan.
Kontrol Server Web memungkinkan Anda menambahkan fungsionalitas ke elemen DOM klien dengan menggunakan kontrol klien. Pembantu Tag tidak memiliki DOM.
Kontrol Server Web mencakup deteksi browser otomatis. Pembantu Tag tidak memiliki pengetahuan tentang browser.
Beberapa Pembantu Tag dapat bertindak pada elemen yang sama (lihat Menghindari konflik Pembantu Tag) sementara Anda biasanya tidak dapat menyusun kontrol Server Web.
Pembantu Tag dapat mengubah tag dan konten elemen HTML yang dicakup, tetapi tidak secara langsung memodifikasi hal lain di halaman. Kontrol Server Web memiliki cakupan yang kurang spesifik dan dapat melakukan tindakan yang memengaruhi bagian lain halaman Anda; mengaktifkan efek samping yang tidak diinginkan.
Kontrol Server Web menggunakan pengonversi jenis untuk mengonversi string menjadi objek. Dengan Bantuan Tag, Anda bekerja secara asli di C#, sehingga Anda tidak perlu melakukan konversi jenis.
Kontrol Server Web digunakan System.ComponentModel untuk mengimplementasikan perilaku run-time dan design-time komponen dan kontrol. System.ComponentModel termasuk kelas dasar dan antarmuka untuk menerapkan atribut dan pengonversi jenis, pengikatan ke sumber data, dan komponen lisensi. Berbeda dengan Pembantu Tag, yang biasanya berasal dari TagHelper, dan TagHelper kelas dasar hanya mengekspos dua metode, Process dan ProcessAsync.