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

Gönderen Rick Anderson

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) alması garanti edilir. 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ı ve genel GitHub depolarında ve NuGet paketleri olarak kullanılabilir. 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, LabelTagHelper yerleşik öznitelikler uygulandığında LabelTagHelper HTML <label> öğesini hedefleyebilir. HTML Yardımcıları hakkında bilginiz varsa, 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. Etiket Yardımcıları, HTML Yardımcıları ile karşılaştırıldığında 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 Core Razor bileşenleri.

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

HTML dostu bir geliştirme deneyimi

Çoğunlukla Etiket Razor Yardımcıları kullanılarak yapılan 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 sunucu tarafı biçimlendirme oluşturmaya önceki yaklaşım olan HTML Yardımcıları'nın keskin karşıtlığıdır Razor . Etiket Yardımcıları, HTML Yardımcıları ile karşılaştırıldığında 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 hale getirmenin ve daha sağlam, güvenilir ve sürdürülebilir kod üretmenin bir yolu

Örneğin, geçmişte görüntüleri güncelleştirmeye ilişkin 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 görüntü 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 hem çok yoğun iş gücü hem de hataya eğilimli (bir başvuruyu kaçırabilir, yanlışlıkla yanlış dizeyi girebilirsiniz vb.) Yerleşik ImageTagHelper , bunu sizin için otomatik olarak yapabilir. görüntü ImageTagHelper 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ş gücü tasarrufu, 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>Görünümler/Hesap klasöründeki birçok görünümde kullanılan öğe özniteliğini asp-for içerir. Bu öznitelik, belirtilen model özelliğinin adını işlenmiş 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 tarafından For kullanılabilir hale getirilirLabelTagHelper. 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ı Pages/_ViewImports.cshtmlvarsayılan olarak Sayfalar klasöründeki ve alt klasörlerindeki tüm dosyalar tarafından devralınır ve Etiket Yardımcıları'nı kullanılabilir hale getirir. Yukarıdaki kod, belirtilen derlemedeki (Microsoft.AspNetCore.Mvc.TagHelpers) tüm Etiket Yardımcılarının Görünümler dizinindeki veya alt dizinindeki tüm görünüm dosyaları için kullanılabilir olacağını belirtmek için joker karakter sözdizimini ("*") kullanır. Sonra gelen ilk parametre @addTagHelper yükleniyor 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 tüm Etiket Yardımcılarını kullanıma açmak için ( AuthoringTagHelpers adlı bir derleme oluşturur), 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 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, 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 dosyada kullanmak@removeTagHelper, belirtilen Etiket Yardımcısı'nı Klasör'deki tüm görünümlerden kaldırır.Views/Folder/_ViewImports.cshtml

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

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 eklenebilir olduğundan _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>

Açma ve kapatma etiketine Etiket Yardımcısı geri çevirme karakterini 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 öğe 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 öğe etkinleştirilmezken <span> Etiket Yardımcısı etkindir.

Razor markup with Tag Helper prefix set to

için @addTagHelper geçerli olan aynı hiyerarşi kuralları için @tagHelperPrefixde geçerlidir.

Kendi Kendini Kapatan Etiket Yardımcıları

Birçok Etiket Yardımcısı kendi kendine kapanan etiketler olarak kullanılamaz. Bazı Etiket Yardımcıları kendi kendine kapanan etiketler olarak tasarlanmıştır. Kendi kendine kapanacak şekilde tasarlanmamış bir Etiket Yardımcısı kullanıldığında, işlenen çıkış gizlenir. Etiket Yardımcısı'nın kendi kendine kapatılması, işlenen çıkışta kendi kendini kapatan bir etiketle sonuçlanır. Daha fazla bilgi için, Yazma Etiketi Yardımcıları'ndakibu nota bakın.

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

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

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

Yukarıdaki kod şöyle 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, disabled veya LicenseIdnullise Model özniteliği kaldırılır.

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

Öznitelikler etiket yardımcılarının tek tek örneklerini yapılandırmak için kullanılabilirken, ITagHelperInitializer<TTagHelper> 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, uygulamanın 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 wwwrootstatik bir dosya için sürüm oluşturması için bkz . Dosyaları birden çok konumdan sunma

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

BIR 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

simgesi, öğ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ı kullanıldığında yazı tipi koyu mordur. "Koyu" temasını kullanıyorsanız yazı tipi kalın deniz mavisi olur. 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 , böylece RegisterViewModel seçeneği 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

The user types

Etiket Yardımcıları ile HTML Yardımcıları karşılaştırması

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ı "caption" 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# dilini @ simge (özellik adı) olarak yorumlamaya @class= zorlamak için sembolünü kullanırsınız. Bir ön uç tasarımcısına (HTML/CSS/JavaScript ve diğer istemci teknolojilerine aşina olan ancak C# ve Razorile aşina 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 bir arka planla görüntüler. Örneğin, AntiForgeryToken HTML Yardımcısı:

@Html.AntiForgeryToken()

gri arka plan ile görüntülenir. Kaydet 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 düşürülür. 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 "Email" değerine sahiptir, ancak "E-posta" bir dize değildir. Bu bağlamda , "Email", için RegisterViewModelC# model ifadesi özelliğidir.

Visual Studio düzenleyicisi, yazmaç formunun Etiket Yardımcısı yaklaşımında tüm işaretlemeyi yazmanıza yardımcı olurken, Visual Studio HTML Yardımcıları yaklaşımındaki kodların çoğu için 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 bir yaşam döngüsüne sahiptir.

  • Web Sunucusu denetimleri, istemci denetimi kullanarak istemci Belge Nesne Modeli (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ı tarayıcı hakkında bilgi sahibi değildir.

  • Genellikle 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 hiçbir şeyi 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 oluşturur ve TagHelper temel sınıf yalnızca iki yöntem ve ProcessAsyncsunarProcess.

Etiket Yardımcısı öğesi yazı tipini özelleştirme

Araç>Seçenekleri>Ortam>Yazı Tipleri ve Renkleri'nden yazı tipini ve renklendirmeyi özelleştirebilirsiniz:

Options dialog in Visual Studio

Yerleşik ASP.NET Çekirdek Etiket Yardımcıları

Tutturucu Etiketi Yardımcısı

Önbellek Etiketi Yardımcısı

Bileşen Etiketi Yardımcısı

Dağıtılmış Önbellek Etiketi Yardımcısı

Ortam Etiketi Yardımcısı

Form Etiketi Yardımcısı

Form Eylem Etiketi Yardımcısı

Görüntü Etiketi Yardımcısı

Giriş Etiketi Yardımcısı

Etiket Etiketi Yardımcısı

Bağlantı Etiketi Yardımcısı

Kısmi Etiket Yardımcısı

Betik Etiketi Yardımcısı

Etiket Yardımcısı'nın seçilmesi

Textarea Etiket Yardımcısı

Doğrulama İletisi Etiketi Yardımcısı

Doğrulama Özeti Etiket Yardımcısı

Ek kaynaklar