ASP.NET Core’da Etiket Yardımcıları

Makale
11/30/2023

Etiket Yardımcıları nedir?

Etiket Yardımcıları, sunucu tarafı kodunun dosyalarda HTML öğeleri Razor oluşturma ve işlemeye katılmasını sağlar. Örneğin, yerleşik ImageTagHelper görüntü adına bir sürüm numarası ekleyebilir. Görüntü her değiştiğinde, sunucu görüntü için yeni bir benzersiz sürüm oluşturur, bu nedenle istemcilerin geçerli görüntüyü (eski önbelleğe alınmış görüntü yerine) almaları garanti edilir. Genel GitHub depolarında ve NuGet paketleri olarak form oluşturma, bağlantılar, varlıkları yükleme ve daha fazlası gibi yaygın görevler için birçok yerleşik Etiket Yardımcısı vardır. Etiket Yardımcıları C# dilinde yazılmıştır ve öğe adına, öznitelik adına veya üst etikete göre HTML öğelerini hedefler. Örneğin, yerleşik öznitelikler uygulandığında LabelTagHelperLabelTagHelper HTML <label> öğesini hedefleyebilir. HTML Yardımcıları hakkında bilgi sahibiyseniz, Etiket Yardımcıları görünümlerde Razor HTML ve C# arasındaki açık geçişleri azaltır. Çoğu durumda, HTML Yardımcıları belirli bir Etiket Yardımcısı'na alternatif bir yaklaşım sağlar, ancak Etiket Yardımcılarının HTML Yardımcılarının yerini almadığını ve her HTML Yardımcısı için bir Etiket Yardımcısı olmadığını bilmek önemlidir. HTML Yardımcıları ile karşılaştırıldığında Etiket Yardımcıları , farklılıkları daha ayrıntılı olarak açıklar.

Etiket Yardımcıları bileşenlerde Razor desteklenmez. Daha fazla bilgi için bkz . ASP.NET Çekirdek Razor bileşenleri.

Etiket Yardımcıları ne sağlar?

HTML dostu bir geliştirme deneyimi

Çoğunlukla Etiket Razor Yardımcılarını kullanan işaretleme standart HTML'ye benzer. HTML/CSS/JavaScript ile yakınsanan ön uç tasarımcıları C# Razor söz dizimlerini öğrenmeden düzenleyebilirRazor.

HTML ve Razor işaretleme oluşturmak için zengin bir IntelliSense ortamı

Bu, görünümlerde işaretlemenin sunucu tarafı oluşturulmasına önceki yaklaşım olan HTML Yardımcılarının keskin karşıtlığındadır Razor . HTML Yardımcıları ile karşılaştırıldığında Etiket Yardımcıları , farklılıkları daha ayrıntılı olarak açıklar. Etiket Yardımcıları için IntelliSense desteği IntelliSense ortamını açıklar. C# söz dizimi konusunda Razor deneyimli geliştiriciler bile Etiket Yardımcılarını kullanarak C# Razor işaretlemesi yazmaktan daha üretkendir.

Yalnızca sunucuda bulunan bilgileri kullanarak daha üretken ve daha sağlam, güvenilir ve sürdürülebilir kod üretmenizi sağlamanın bir yolu

Örneğin, geçmişte resimleri güncelleştirmeye yönelik mantra, görüntüyü değiştirdiğinizde resmin adını değiştirmekti. Görüntüler performans nedenleriyle agresif bir şekilde önbelleğe alınmalıdır ve bir görüntünün adını değiştirmediğiniz sürece istemcilerin eski bir kopya alma riskini alırsınız. Geçmişte, bir resim düzenlendikten sonra adın değiştirilmesi ve web uygulamasındaki görüntüye yapılan her başvurunun güncelleştirilmiş olması gerekiyordu. Bu çok yoğun iş gücüyle değil, aynı zamanda hataya eğilimli (bir başvuruyu kaçırabilir, yanlışlıkla yanlış dizeyi girebilirsiniz vb.) Yerleşik ImageTagHelper olarak bunu sizin için otomatik olarak yapabilirsiniz. ImageTagHelper görüntü adına bir sürüm numarası ekleyebilir, böylece görüntü her değiştiğinde sunucu otomatik olarak görüntü için yeni bir benzersiz sürüm oluşturur. İstemcilerin geçerli görüntüyü alması garanti edilir. Bu sağlamlık ve işçilik tasarrufları, kullanılarak ImageTagHelpertemelde ücretsiz olarak sunulur.

Yerleşik Etiket Yardımcılarının çoğu standart HTML öğelerini hedefler ve öğe için sunucu tarafı öznitelikleri sağlar. Örneğin, <input> Views/Account klasöründeki birçok görünümde kullanılan öğesi özniteliğini asp-for içerir. Bu öznitelik, belirtilen model özelliğinin adını işlenen HTML'ye ayıklar. Aşağıdaki modele sahip bir Razor görünüm düşünün:

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; }
}

Aşağıdaki Razor işaretleme:

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

Aşağıdaki HTML'yi oluşturur:

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

asp-for özniteliği içindeki özelliği LabelTagHelpertarafından For kullanılabilir hale getirilir. Daha fazla bilgi için bkz . Yazar Etiketi Yardımcıları .

Etiket Yardımcısı kapsamını yönetme

Etiket Yardımcıları kapsamı , @removeTagHelperve "!" geri çevirme karakterinin @addTagHelperbirleşimiyle denetlenir.

`@addTagHelper` Etiket Yardımcılarını kullanılabilir hale getirir

AuthoringTagHelpers adlı yeni bir ASP.NET Core web uygulaması oluşturursanız projenize aşağıdaki Views/_ViewImports.cshtml dosya eklenir:

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

yönergesi, @addTagHelper Etiket Yardımcılarını görünümde kullanılabilir hale getirir. Bu durumda, görünüm dosyası varsayılan olarak Sayfalar klasöründeki ve alt klasörlerindeki tüm dosyalar tarafından devralınan ve Etiket Yardımcıları'nın kullanılabilir hale getirildiği dosyasıdırPages/_ViewImports.cshtml. Yukarıdaki kod, belirtilen derlemedeki tüm Etiket Yardımcılarının (Microsoft.AspNetCore.Mvc.TagHelpers) Görünümler dizinindeki veya alt dizinindeki her görünüm dosyasında kullanılabilir olacağını belirtmek için joker karakter sözdizimini ("*") kullanır. Sonraki ilk parametre @addTagHelper yüklenecek Etiket Yardımcılarını belirtir (tüm Etiket Yardımcıları için "*" kullanıyoruz) ve ikinci parametre "Microsoft.AspNetCore.Mvc.TagHelpers", Etiket Yardımcılarını içeren derlemeyi belirtir. Microsoft.AspNetCore.Mvc.TagHelpers , yerleşik ASP.NET Çekirdek Etiket Yardımcıları'nın derlemesidir.

Bu projedeki (AuthoringTagHelpers adlı bir derleme oluşturan) tüm Etiket Yardımcılarını kullanıma açmak için aşağıdakileri kullanırsınız:

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

Projeniz varsayılan ad alanına ()AuthoringTagHelpers.TagHelpers.EmailTagHelper sahip bir EmailTagHelper ad alanı içeriyorsa, Etiket Yardımcısı'nın tam adını (FQN) sağlayabilirsiniz:

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

FQN kullanarak bir görünüme Etiket Yardımcısı eklemek için önce FQN ' yi (AuthoringTagHelpers.TagHelpers.EmailTagHelper ) ve ardından derleme adını (AuthoringTagHelpers) eklersiniz. Çoğu geliştirici "*" joker karakter söz dizimini kullanmayı tercih eder. Joker karakter söz dizimi, bir FQN'de sonek olarak "*" joker karakterini eklemenize olanak tanır. Örneğin, aşağıdaki yönergelerden herhangi biri öğesini EmailTagHelpergetirir:

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

Daha önce belirtildiği gibi, yönergesini @addTagHelper dosyaya Views/_ViewImports.cshtml eklemek, Etiket Yardımcısı'nı Görünümler dizinindeki ve alt dizinlerindeki tüm görüntüleme dosyaları için kullanılabilir hale getirir. Etiket Yardımcısı'nı @addTagHelper yalnızca bu görünümlere göstermeyi kabul etmek istiyorsanız, yönergesini belirli görünüm dosyalarında kullanabilirsiniz.

`@removeTagHelper` Etiket Yardımcılarını kaldırır

ile @removeTagHelper aynı iki parametreye @addTagHelpersahiptir ve daha önce eklenmiş bir Etiket Yardımcısı'nı kaldırır. Örneğin, @removeTagHelper belirli bir görünüme uygulanan, belirtilen Etiket Yardımcısı'nı görünümden kaldırır. Bir Views/Folder/_ViewImports.cshtml dosyada kullanmak@removeTagHelper, belirtilen Etiket Yardımcısı'nı Klasör'deki tüm görünümlerden kaldırır.

Etiket Yardımcısı kapsamını dosyayla denetleme `_ViewImports.cshtml`

Herhangi bir görünüm klasörüne bir _ViewImports.cshtml ekleyebilirsiniz ve görünüm altyapısı hem bu dosyadan hem de dosyadan Views/_ViewImports.cshtml yönergeleri uygular. Görünümler için Home boş Views/Home/_ViewImports.cshtml bir dosya eklediyseniz, dosya eklendiğinden _ViewImports.cshtml hiçbir değişiklik olmaz. Dosyaya Views/Home/_ViewImports.cshtml eklediğiniz tüm @addTagHelper yönergeler (varsayılan Views/_ViewImports.cshtml dosyada olmayanlar) bu Etiket Yardımcılarını yalnızca klasördeki Home görünümlerde kullanıma sunar.

Tek tek öğeleri geri çevirme

Etiket Yardımcısı geri çevirme karakteri ("!") ile öğe düzeyinde bir Etiket Yardımcısı'nı devre dışı bırakabilirsiniz. Örneğin, Email içinde Etiket Yardımcısı geri çevirme karakteriyle doğrulama devre dışı bırakılır <span> :

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

Etiket Yardımcısı geri çevirme karakterini açma ve kapatma etiketine uygulamanız gerekir. (Visual Studio düzenleyicisi, açma etiketine bir tane eklediğinizde kapatma etiketine otomatik olarak geri çevirme karakterini ekler). Geri çevirme karakterini ekledikten sonra, öğesi ve Etiket Yardımcısı öznitelikleri artık ayırt edici bir yazı tipinde görüntülenmez.

Etiket Yardımcısı kullanımını açık hale getirmek için kullanma `@tagHelperPrefix`

yönergesi, @tagHelperPrefix Etiket Yardımcısı desteğini etkinleştirmek ve Etiket Yardımcısı kullanımını açık hale getirmek için bir etiket ön eki dizesi belirtmenize olanak tanır. Örneğin, dosyaya aşağıdaki işaretlemeyi Views/_ViewImports.cshtml ekleyebilirsiniz:

@tagHelperPrefix th:

Aşağıdaki kod görüntüsünde Etiket Yardımcısı ön eki olarak th:ayarlanmıştır, bu nedenle yalnızca ön ekini th: kullanan öğeler Etiket Yardımcılarını destekler (Etiket Yardımcısı özellikli öğelerin ayırt edici bir yazı tipi vardır). <label> ve <input> öğeleri Etiket Yardımcısı ön ekini içerir ve Etiket Yardımcısı etkinken <span> öğesi etkinleştirilmez.

Razor markup with Tag Helper prefix set to

için @addTagHelper geçerli olan hiyerarşi kuralları için de geçerlidir @tagHelperPrefix.

Kendi Kendini Kapatan Etiket Yardımcıları

Birçok Etiket Yardımcısı kendi kendini kapatan etiketler olarak kullanılamaz. Bazı Etiket Yardımcıları kendi kendini kapatan etiketler olacak şekilde tasarlanmıştır. Kendi kendine kapanacak şekilde tasarlanmamış bir Etiket Yardımcısı kullanmak, işlenen çıkışı bastırır. Etiket Yardımcısı'nın kendi kendini kapatması, işlenen çıktıda kendi kendini kapatan bir etiketle sonuçlanır. Daha fazla bilgi için, Yazma Etiketi Yardımcıları'ndaki bu nota bakın.

Etiket Yardımcıları özniteliği/bildiriminde C#

Etiket Yardımcıları öğenin özniteliğinde veya etiket bildirimi alanında C# öğesine izin vermez. Örneğin, aşağıdaki kod geçerli değil:

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

Yukarıdaki kod şu şekilde yazılabilir:

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

Normalde işleç, @ işlenen HTML işaretlemesine bir ifadenin metinsel gösterimini ekler. Ancak, bir ifade mantıksal falseolarak değerlendirildiğinde, çerçeve bunun yerine özniteliğini kaldırır. Yukarıdaki örnekte özniteliği veya disabled ise ModelLicenseId olarak true ayarlanmıştırnull.

Etiket yardımcı başlatıcıları

Öznitelikler etiket yardımcılarının tek tek örneklerini yapılandırmak için kullanılabilir, ITagHelperInitializer<TTagHelper> ancak belirli bir türe ait tüm etiket yardımcı örneklerini yapılandırmak için kullanılabilir. Uygulamadaki tüm örnekleri ScriptTagHelper için özniteliğini veya AppendVersion özelliğini yapılandıran asp-append-version aşağıdaki etiket yardımcısı başlatıcı örneğini göz önünde bulundurun:

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

Başlatıcıyı kullanmak için, uygulamayı başlatma işleminin bir parçası olarak kaydederek yapılandırın:

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

Wwwroot dışında Etiket Yardımcısı otomatik sürüm oluşturma

Etiket Yardımcısı'nın dışında wwwrootbir statik dosya için sürüm oluşturması için bkz. Birden çok konumdan dosya sunma

Etiket Yardımcıları için IntelliSense desteği

HTML <label> öğesi yazmayı göz önünde bulundurun. Visual Studio düzenleyicisine girdiğiniz <l anda IntelliSense eşleşen öğeleri görüntüler:

After typing

Yalnızca HTML yardımı almakla kalmaz, aynı zamanda simgeyi de (altında "" bulunan "<>@" simgesi) alırsınız.

The

Simge, öğeyi Etiket Yardımcıları tarafından hedeflenen olarak tanımlar. Saf HTML öğeleri (örneğin fieldset), "<>" simgesini görüntüler.

Saf HTML <label> etiketi, HTML etiketini (varsayılan Visual Studio renk temasıyla) kahverengi yazı tipinde, öznitelikleri kırmızı ve öznitelik değerlerini mavi olarak görüntüler.

Example

girdikten <labelsonra, IntelliSense kullanılabilir HTML/CSS özniteliklerini ve Etiket Yardımcısı tarafından hedeflenen öznitelikleri listeler:

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

IntelliSense deyiminin tamamlanması, deyimi seçili değerle tamamlamak için sekme tuşuna girmenizi sağlar:

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

Etiket Yardımcısı özniteliği girildiğinde etiket ve öznitelik yazı tipleri değişir. Varsayılan Visual Studio "Mavi" veya "Açık" renk temasını kullanan yazı tipi kalın mordur. "Koyu" temasını kullanıyorsanız yazı tipi kalın teal şeklindedir. Bu belgedeki resimler varsayılan tema kullanılarak alınmıştır.

The user selected

Çift tırnak ("") içine Visual Studio CompleteWord kısayolunu (Ctrl +boşluk çubuğu varsayılandır) girebilir ve C# sınıfında olduğunuz gibi artık C# dilindesiniz. IntelliSense, sayfa modelinde tüm yöntemleri ve özellikleri görüntüler. Özellik türü olduğundan ModelExpressionyöntemler ve özellikler kullanılabilir. Aşağıdaki görüntüde görünümü düzenliyorum Register , bu nedenle RegisterViewModel kullanılabilir.

The user types

IntelliSense, sayfadaki model için kullanılabilen özellikleri ve yöntemleri listeler. Zengin IntelliSense ortamı CSS sınıfını seçmenize yardımcı olur:

The user types

HTML Yardımcıları ile karşılaştırıldığında Etiket Yardımcıları

Etiket Yardımcıları görünümlerdeki Razor HTML öğelerine eklenirken, HTML Yardımcıları görünümlerde Razor HTML ile kesişen yöntemler olarak çağrılır. CSS sınıfı "başlık" ile bir HTML etiketi oluşturan aşağıdaki Razor işaretlemeyi göz önünde bulundurun:

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

at (@) simgesi bunun kodun başlangıcı olduğunu söyler Razor . Sonraki iki parametre ("Ad" ve "Ad:") dizelerdir, bu nedenle IntelliSense yardımcı olamaz. Son bağımsız değişken:

new {@class="caption"}

Öznitelikleri temsil etmek için kullanılan anonim bir nesnedir. class C# dilinde ayrılmış bir anahtar sözcük olduğundan, C# öğesini simge (özellik adı) olarak yorumlamaya @class= zorlamak için simgesini kullanırsınız@. Ön uç tasarımcısına (HTML/CSS/JavaScript ve diğer istemci teknolojilerine aşina olan ancak C# ve Razorhakkında bilgi sahibi olmayan biri) satırın çoğu yabancıdır. Satırın tamamı IntelliSense yardımı olmadan yazılmalıdır.

kullanılarak LabelTagHelperaynı işaretleme şu şekilde yazılabilir:

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

Etiket Yardımcısı sürümüyle, Visual Studio düzenleyicisine girer girmez <l IntelliSense eşleşen öğeleri görüntüler:

The user types

IntelliSense, satırın tamamını yazmanıza yardımcı olur.

Aşağıdaki kod görüntüsünde, Visual Studio'da bulunan ASP.NET 4.5.x MVC şablonundan oluşturulan görünümün Form bölümü Views/Account/Register.cshtmlRazor gösterilmektedir.

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

Visual Studio düzenleyicisi, C# kodunu gri arka planla görüntüler. Örneğin, AntiForgeryToken HTML Yardımcısı:

@Html.AntiForgeryToken()

gri arka plan ile görüntülenir. Kayıt görünümündeki işaretlemelerin çoğu C# şeklindedir. Etiket Yardımcılarını kullanarak bunu eşdeğer yaklaşımla karşılaştırın:

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

İşaretlemeyi okumak, düzenlemek ve korumak, HTML Yardımcıları yaklaşımından çok daha temiz ve daha kolaydır. C# kodu, sunucunun bilmesi gereken en düşük değere indirilir. Visual Studio düzenleyicisi, Etiket Yardımcısı tarafından hedeflenen işaretlemeyi ayırt edici bir yazı tipinde görüntüler.

E-posta grubunu göz önünde bulundurun:

<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>

"asp-" özniteliklerinin her biri "E-posta" değerine sahiptir, ancak "E-posta" bir dize değildir. Bu bağlamda "E-posta", için RegisterViewModelC# model ifadesi özelliğidir.

Visual Studio düzenleyicisi, yazmaç formunun Etiket Yardımcısı yaklaşımında tüm işaretlemeleri yazmanıza yardımcı olurken, Visual Studio HTML Yardımcıları yaklaşımındaki kodların çoğu için hiçbir yardım sağlamaz. Etiket Yardımcıları için IntelliSense desteği, Visual Studio düzenleyicisinde Etiket Yardımcılarıyla çalışma konusunda ayrıntılı bir şekilde anlatılmaktadır.

Web Sunucusu Denetimleri ile karşılaştırıldığında Etiket Yardımcıları

Etiket Yardımcıları ilişkili oldukları öğeye sahip değildir; yalnızca öğenin ve içeriğin işlenmesine katılırlar. ASP.NET Web Sunucusu Denetimleri bir sayfada bildirilir ve çağrılır.
ASP.NET Web Sunucusu Denetimleri geliştirmeyi ve hata ayıklamayı zorlaştırabilecek önemsiz olmayan bir yaşam döngüsüne sahiptir.
Web Sunucusu denetimleri, istemci denetimi kullanarak istemci DOM öğelerine işlevsellik eklemenize olanak sağlar. Etiket Yardımcılarının DOM'ları yoktur.
Web Sunucusu denetimleri otomatik tarayıcı algılamayı içerir. Etiket Yardımcılarının tarayıcı hakkında hiçbir bilgisi yoktur.
Web Sunucusu denetimleri oluşturamazken birden çok Etiket Yardımcısı aynı öğe üzerinde işlem yapabilir (bkz . Etiket Yardımcısı çakışmalarını önleme).
Etiket Yardımcıları, kapsamı belirlenmiş HTML öğelerinin etiketini ve içeriğini değiştirebilir, ancak sayfadaki diğer öğeleri doğrudan değiştirmez. Web Sunucusu denetimleri daha az belirli bir kapsama sahiptir ve sayfanızın diğer bölümlerini etkileyen eylemler gerçekleştirebilir; istenmeyen yan etkileri etkinleştirme.
Web Sunucusu denetimleri, dizeleri nesnelere dönüştürmek için tür dönüştürücüleri kullanır. Etiket Yardımcıları ile C# dilinde yerel olarak çalışırsınız, bu nedenle tür dönüştürme yapmanız gerekmez.
Web Sunucusu denetimleri, bileşenlerin ve denetimlerin çalışma zamanı ve tasarım zamanı davranışını uygulamak için kullanılır System.ComponentModel . System.ComponentModel öznitelikleri ve tür dönüştürücülerini uygulamaya, veri kaynaklarına bağlamaya ve lisanslama bileşenlerine yönelik temel sınıfları ve arabirimleri içerir. Genellikle öğesinden TagHelpertüretilen Etiket Yardımcıları ile karşıtlık sağlar TagHelper ve temel sınıfı yalnızca iki yöntem ve ProcessAsyncsunarProcess.