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) 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 LabelTagHelper
LabelTagHelper
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 ImageTagHelper
temelde ü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ı , @removeTagHelper
ve "!" geri çevirme karakterinin @addTagHelper
birleş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 EmailTagHelper
getirir:
@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 @addTagHelper
sahiptir 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.
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 false
olarak değerlendirildiğinde, çerçeve bunun yerine özniteliğini kaldırır. Yukarıdaki örnekte özniteliği veya disabled
ise Model
LicenseId
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 wwwroot
bir 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:
Yalnızca HTML yardımı almakla kalmaz, aynı zamanda simgeyi de (altında "" bulunan "<>@" simgesi) alırsınız.
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.
girdikten <label
sonra, IntelliSense kullanılabilir HTML/CSS özniteliklerini ve Etiket Yardımcısı tarafından hedeflenen öznitelikleri listeler:
IntelliSense deyiminin tamamlanması, deyimi seçili değerle tamamlamak için sekme tuşuna girmenizi sağlar:
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.
Ç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 ModelExpression
yöntemler ve özellikler kullanılabilir. Aşağıdaki görüntüde görünümü düzenliyorum Register
, bu nedenle RegisterViewModel
kullanılabilir.
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:
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 LabelTagHelper
aynı 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:
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.cshtml
Razor gösterilmektedir.
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:
İş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 RegisterViewModel
C# 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 öğesindenTagHelper
türetilen Etiket Yardımcıları ile karşıtlık sağlarTagHelper
ve temel sınıfı yalnızca iki yöntem veProcessAsync
sunarProcess
.
Etiket Yardımcısı öğesi yazı tipini özelleştirme
Araç>Seçenekleri>Ortam>Yazı Tipleri ve Renkleri'nden yazı tipini ve renklendirmeyi özelleştirebilirsiniz:
Yerleşik ASP.NET Core Etiket Yardımcıları
Ek kaynaklar
- Yazar Etiketi Yardımcıları
- Formlarla Çalışma
- GitHub'da TagHelperSamples, Bootstrap ile çalışmaya yönelik Etiket Yardımcısı örneklerini içerir.
ASP.NET Core
Geri Bildirim
https://aka.ms/ContentUserFeedback.
Çok yakında: 2024 boyunca, içerik için geri bildirim mekanizması olarak GitHub Sorunları’nı kullanımdan kaldıracak ve yeni bir geri bildirim sistemiyle değiştireceğiz. Daha fazla bilgi için bkz.Gönderin ve geri bildirimi görüntüleyin