Aracılığıyla paylaş

ASP.NET Core Blazor temelleri

Not

Bu, bu makalenin en son sürümü değildir. Geçerli sürüm için bu makalenin .NET 9 sürümüne bakın.

Uyarı

ASP.NET Core'un bu sürümü artık desteklenmiyor. Daha fazla bilgi için bkz. .NET ve .NET Core Destek İlkesi. Geçerli sürüm için bu makalenin .NET 9 sürümüne bakın.

Önemli

Bu bilgiler, ticari olarak piyasaya sürülmeden önce önemli ölçüde değiştirilebilen bir yayın öncesi ürünle ilgilidir. Burada verilen bilgilerle ilgili olarak Microsoft açık veya zımni hiçbir garanti vermez.

Geçerli sürüm için bu makalenin .NET 9 sürümüne bakın.

Temel makaleler , temel Blazor kavramlar hakkında rehberlik sağlar. Bazı kavramlar, bu makalenin Razorsonraki bölümünde daha ayrıntılı olarak açıklanan ve Bileşenler makalelerinde ayrıntılı olarak ele alınan temel bileşenler anlayışına bağlıdır.

Statik ve etkileşimli işleme kavramları

Razor bileşenleri statik olarak işlenir veya etkileşimli olarak işlenir.

Statik veya statik işleme , bileşenin kullanıcı ile .NET/C# kodu arasında etkileşim için kapasite olmadan işlendiği anlamına gelen sunucu tarafı bir senaryodur. JavaScript ve HTML DOM olayları etkilenmez, ancak istemcideki hiçbir kullanıcı olayı sunucuda çalışan .NET ile işlenemez.

Etkileşimli/etkileşim veya etkileşimli işleme , bileşenin C# kodu aracılığıyla .NET olaylarını ve bağlamayı işleme kapasitesine sahip olduğu anlamına gelir. .NET olayları ve bağlama, ASP.NET Core çalışma zamanı tarafından sunucuda veya WebAssembly tabanlı Blazor çalışma zamanı tarafından istemcideki tarayıcıda işlenir.

Önemli

Bir Blazor Web App kullanırken, belgelerdeki örnek bileşenlerin Blazor çoğu, makalelerde ele alınan kavramların çalışması ve gösterilmesi için etkileşim gerektirir. Bir makale tarafından sağlanan örnek bir bileşeni Blazor Web Appiçinde test ettiğinizde, uygulamanın genel etkileşimli çalışma özelliğini benimsediğinden veya bileşenin etkileşimli işleme modunu kullandığından emin olun. Bu konu hakkında daha fazla bilgi, belge kümesinin ilerleyen Blazor bölümlerinde yer alan Bileşenler bölümündeki tarafından sağlanır.

Bu kavramlar ve statik ve etkileşimli işlemeyi denetleme hakkında daha fazla bilgi için belgelerin devamında yer alan ASP.NET Core Blazor işleme modları makalesinde Blazor bulabilirsiniz.

İstemci ve sunucu işleme kavramları

Belgeler boyunca Blazor , kullanıcının sisteminde gerçekleşen etkinliğin istemci veya istemci tarafında gerçekleştiği söylenir. Bir sunucuda gerçekleşen etkinliğin sunucuda veya sunucu tarafında gerçekleştiği söylenir.

İşleme terimi, tarayıcıların görüntülendiği HTML işaretlemesini üretme anlamına gelir.

  • İstemci tarafı işleme (CSR), son HTML işaretlemesinin istemcideki .NET WebAssembly çalışma zamanı tarafından oluşturulduğu anlamına gelir. Uygulamanın istemci tarafından oluşturulan kullanıcı arabirimi için bu tür bir işleme için sunucudan istemciye HTML gönderilmez. Kullanıcının sayfayla etkileşimi varsayılır. İstemci tarafında statik işleme diye bir kavram yoktur. CSR'nin etkileşimli olduğu varsayılır, bu nedenle sektör veya belgelerde "etkileşimli istemci tarafı işleme" ve "Blazor CSR" kullanılmaz.

  • Sunucu tarafı işleme (SSR), son HTML işaretlemesinin sunucudaki ASP.NET Core çalışma zamanı tarafından oluşturulduğu anlamına gelir. HTML, istemcinin tarayıcısı tarafından görüntülenmesi için bir ağ üzerinden istemciye gönderilir. Uygulamanın sunucu tarafından oluşturulan kullanıcı arabirimi için bu işleme türünde istemci tarafından HTML oluşturulmaz. SSR iki çeşit olabilir:

    • Statik SSR: Sunucu, kullanıcı etkileşimi veya bileşen durumunu koruma sağlamayan Razor statik HTML üretir.
    • Etkileşimli SSR: Blazor olaylar kullanıcı etkileşimi sağlar ve Razor bileşen durumu çerçeve tarafından Blazor korunur.

  • Ön kayıt , işlenen denetimler için olay işleyicilerini etkinleştirmeden başlangıçta sunucudaki sayfa içeriğini işleme işlemidir. Sunucu, uygulamanın kullanıcılara daha duyarlı hissetmesini sağlayan ilk isteğe yanıt olarak sayfanın HTML kullanıcı arabirimini mümkün olan en kısa sürede verir. Ön kayıt, arama motorlarının sayfa derecesini hesaplamak için kullandığı ilk HTTP yanıtının içeriğini işleyerek Arama Altyapısı İyileştirmesini (SEO) da geliştirebilir. Prerendering işlemi, her zaman sunucuda veya istemcide gerçekleşen son işleme ile tamamlanır.

Razor bileşenleri

Blazoruygulamalar genellikle yalnızca bileşenler olarak adlandırılan Razor. Bileşen, sayfa, iletişim kutusu veya veri girişi formu gibi bir kullanıcı arabirimi öğesidir. Bileşenler, .NET derlemelerinde yerleşik olarak kullanılan .NET C# sınıflarıdır.

Razor, bileşenlerin genellikle istemci tarafı UI mantığı ve kompozisyonu için bir Razor işaretleme sayfası biçiminde nasıl yazıldığını ifade eder. Razor, HTML işaretlemesini geliştirici üretkenliği için tasarlanmış C# koduyla birleştirmeye yönelik bir söz dizimidir. Razor dosyaları .razor dosya uzantısını kullanır.

Bazı Blazor geliştiricileri ve çevrimiçi kaynaklar "Blazor bileşenleri" terimini kullansa da, belgelerde bu terim engellenir ve evrensel olarak "Razor bileşenleri" veya "bileşenler" kullanılır.

Blazor belgesi, bileşenleri göstermek ve tartışmak için çeşitli konvansiyonları benimser:

  • Örnekler genellikle ASP.NET Core/C# kodlama kurallarına ve mühendislik yönergelerine bağlıdır. Daha fazla bilgi için aşağıdaki kaynaklara bakın:
  • Proje kodu, dosya yolları ve adları, proje şablonu adları ve diğer özel terimler Amerikan İngilizcesi olarak yazılmıştır ve genellikle kod blokları içine alınmıştır.
  • Bileşenlere genellikle C# sınıf adları (Pascal büyük/küçük harf) ve ardından "bileşen" sözcüğü denir. Örneğin, tipik bir dosya karşıya yükleme bileşeni "FileUpload bileşeni" olarak adlandırılır.
  • Genellikle, bir bileşenin C# sınıf adı dosya adıyla aynıdır.
  • Yönlendirilebilir bileşenler, genellikle kebab-case formatında olan göreli URL'lerini bileşenin sınıf adıyla ayarlarlar. Örneğin, bir FileUpload bileşeni, göreli /file-upload URL'de işlenen bileşene ulaşmak için yönlendirme yapılandırmasını içerir. Yönlendirme ve gezinti , ASP.NET Temel Blazor yönlendirme ve gezinti bölümünde ele alınmıştır.
  • Bir bileşenin birden çok sürümü kullanıldığında, bunlar sıralı olarak numaralandırılır. Örneğin, FileUpload3 bileşenine /file-upload-3 ulaşılır.
  • Razor bir bileşen tanımının (.razor file) en üstündeki yönergeler şu sırayla yerleştirilir: @page, @rendermode (.NET 8 veya üzeri), @using deyimler, alfabetik sırada diğer yönergeler.
  • Üyeler için private gerekli olmasa da, makale örneklerinde ve örnek uygulamalarda erişim değiştiricileri kullanılır. Örneğin private, maxAllowedFiles adlı bir alanı private int maxAllowedFiles = 3; olarak bildirmek için belirtilir.
  • Bileşen parametre değerleri Razor ayrılmış @ bir simge ile başlar, ancak bu zorunlu değildir. Değişmez değerler (örneğin, boole değerleri), anahtar sözcükler (örneğin, this) ve null bileşen parametre değerleri @ ile ön eklenmez, ancak bu yalnızca bir dokümantasyon geleneğidir. İsterseniz, kendi kodunuzda sabitlere @ ön eki ekleyebilirsiniz.
  • C# sınıfları anahtar kelimesinithis kullanır ve kurucularda atanan alanlara alt çizgi (_) ön eki eklemekten kaçınır, bu da ASP.NET Core çerçeve mühendisliği yönergelerinden farklılık gösterir.
  • Birincil oluşturucuları (C# 12 veya üzeri) kullanan örneklerde, birincil oluşturucu parametreleri genellikle doğrudan sınıf üyeleri tarafından kullanılır. Makale örneklerinde, yatay kaydırmayı azaltmak için kod satırları bölünür. Bu boşluklar yürütmeyi etkilemez, ancak projenize yapıştırırken kaldırılabilir.

bileşen söz dizimi hakkında ek bilgiler, ASP.NET Core bileşenlerinin söz dizimi bölümünde sağlanmaktadır.

Aşağıda örnek bir sayaç bileşeni ve Blazor proje şablonundan oluşturulan bir uygulamanın bir bölümü verilmiştir. Ayrıntılı bileşen kapsamı, belgelerin devamında yer alan Bileşenler makalelerinde bulunur. Aşağıdaki örnek, belgelerin devamında Yer alan Bileşenler makalelerine ulaşmadan önce Temel Bilgiler makalelerinde görülen bileşen kavramlarını gösterir.

Counter.razor:

Bileşen, etkileşimli işleme modunun bir üst bileşenden devralındığını veya uygulamaya genel olarak uygulandığını varsayar.

@page "/counter"

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

<p role="status">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount() => currentCount++;
}

Bileşen, etkileşimli işleme modunun bir üst bileşenden devralındığını veya uygulamaya genel olarak uygulandığını varsayar.

@page "/counter"

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

<p role="status">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount() => currentCount++;
}

@page "/counter"

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

<p role="status">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

@page "/counter"

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

<p role="status">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

@page "/counter"

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

@page "/counter"

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

Önceki Counter bileşeni:

  • İlk satırda @page yönergesi ile yolunu ayarlar.
  • Sayfa başlığını ve üstbilgiyi ayarlar.
  • Geçerli sayıyı @currentCount ile gösterir. currentCount, @code bloğunun C# kodunda tanımlanan bir tamsayı değişkenidir.
  • IncrementCount bloğunda da bulunan ve @code değişkeninin değerini artıran currentCount yöntemini tetiklemek için bir düğme görüntüler.

İşleme modları

Temel Bilgiler düğümündeki makaleler işleme modları kavramına başvuruda bulunur. Bu konu, makalelerin Blazor bilgiler düğümünden sonra görünen Bileşenler düğümündeki ASP.NET Core işleme modları makalesinde ayrıntılı olarak ele alınmıştır.

Makale düğümündeki render alma modu kavramlarına yönelik erken referanslar için şu anda yalnızca aşağıdakilere dikkat edin:

içindeki Blazor Web App her bileşen, kullandığı barındırma modelini, nerede işlendiğini ve sunucuda statik olarak işlenip işlenmediğini, sunucuda kullanıcı etkileşimi için işlenip işlenmeyeceğini veya istemcide kullanıcı etkileşimi için işlenip işlenmediğini belirlemek için bir işleme modu benimser (genellikle sunucuda ön oturum açma ile).

Blazor Server ve Blazor WebAssembly .NET 8 öncesi ASP.NET Core sürümlerine yönelik uygulamalar, işleme modlarında değil barındırma modeli kavramlarında sabit kalır. İşleme modları kavramsal olarak .NET 8 veya sonraki sürümlerde Blazor Web App'lere uygulanır.

Aşağıdaki tabloda, Razor içindeki Blazor Web App bileşenlerini işlemek için kullanılabilir işleme modları gösterilmektedir. Bileşen örneği veya bileşen tanımındaki @rendermode yönergesiyle bileşenlere görüntüleme modları uygulanır. Uygulamanın tamamı için bir işleme modu ayarlamak da mümkündür.

Veri Akışı Adı Açıklama Görüntü oluşturma konumu Etkileşimli
Statik Sunucu Statik sunucu tarafı işleme (statik SSR) Sunucu
Etkileşimli Sunucu Etkileşimli sunucu tarafı işleme (etkileşimli SSR) Blazor Server kullanarak Sunucu
Etkileşimli WebAssembly İstemci tarafı işleme (CSR) † kullanarak Blazor WebAssembly Müşteri
Etkileşimli Otomatik Başlangıçta Blazor Server kullanılarak etkileşimli SSR, paket Blazor indirildikten sonraki ziyaretlerde CSR kullanılır. Sunucu, ardından istemci

†İstemci tarafı işlemenin (CSR) etkileşimli olduğu varsayılır. "Etkileşimli istemci tarafı görselleştirme" ve "etkileşimli CSR" sektörde veya belgelerde Blazor kullanılmaz."

İşleme modlarıyla ilgili önceki bilgiler, Temel Bilgiler düğümü makalelerini anlamak için bilmeniz gereken tek şeydir. Blazor ve Blazor makalelerini sırayla okuyorsanız ve bu içeriklere yeniyseniz, Blazor düğümündeki ASP.NET Core işleme modları makalesine ulaşana kadar işleme modları hakkında ayrıntılı bilgileri okumayı erteleyebilirsiniz.

Belge Nesne Modeli (DOM)

Belge Nesne Modeli başvuruları DOM kısaltmasını kullanır.

Daha fazla bilgi edinmek için aşağıdaki kaynaklara bakın:

Uygulamalar için Blazor WebAssembly .NET API'lerinin alt kümesi

Tarayıcıda Blazor WebAssembly tarafından desteklenen belirli .NET API'lerinin seçilmiş bir listesi mevcut değil. Ancak, WebAssembly'de .NET API'lerinin listesini el ile [UnsupportedOSPlatform("browser")] arayabilirsiniz.

Not

.NET başvuru kaynağına yönelik belge bağlantıları genellikle deponun varsayılan dalını yükler ve bu dal .NET'in sonraki sürümü için geçerli geliştirmeyi temsil eder. Belirli bir sürüm için bir etiket seçmek amacıyla Dalları veya etiketleri değiştir açılır listesini kullanın. Daha fazla bilgi için bkz. ASP.NET Core kaynak kodunun sürüm etiketini seçme (dotnet/AspNetCore.Docs #26205).

Daha fazla bilgi edinmek için aşağıdaki kaynaklara bakın:

Örnek uygulamalar

Belge örnek uygulamaları, inceleme ve indirme için kullanılabilir:

Blazor örnek GitHub deposu (dotnet/blazor-samples)

İlk olarak üzerinde çalıştığınız .NET sürümüyle eşleşen sürüm klasörünü seçerek örnek bir uygulama bulun.

Depodaki uygulamaları örnekler:

Depodaki uygulamaları örnekler:

Örnek depo iki tür örnek içerir:

  • Kod parçacığı örnek uygulamaları, makalelerde görünen kod örneklerini sağlar. Bu uygulamalar derlenebilir ancak çalıştırılabilir uygulamalar olmayabilir. Bu uygulamalar yalnızca makalelerde görünen örnek kodu elde etmek için kullanışlıdır.
  • Aşağıdaki senaryolar için Blazor makalelerine eşlik eden örnek uygulamalar derlenir ve çalıştırılır.
    • Blazor Server ve Blazor WebAssembly ile SignalR
    • Blazor WebAssembly kapsamlar etkinleştirilmiş günlüğe kaydetme

Daha fazla bilgi için, depodaki örneklerin listesi ve indirme yönergeleri için bkzBlazor. Örnekler GitHub deposu README dosyası.

ASP.NET Core deposunun Temel Test Uygulaması da çeşitli Blazor senaryolar için yararlı bir örnek kümesidir:

BasicTestApp ASP.NET Çekirdek başvuru kaynağında (dotnet/aspnetcore)

Not

.NET başvuru kaynağına yönelik belge bağlantıları genellikle deponun varsayılan dalını yükler ve bu dal .NET'in sonraki sürümü için geçerli geliştirmeyi temsil eder. Belirli bir sürüm için bir etiket seçmek amacıyla Dalları veya etiketleri değiştir açılır listesini kullanın. Daha fazla bilgi için bkz. ASP.NET Core kaynak kodunun sürüm etiketini seçme (dotnet/AspNetCore.Docs #26205).

Bayt çarpanları

.NET bayt boyutları, 1024'ün kuvvetlerine dayanan ondalık olmayan bayt katlarını ifade etmek için metrik ön ekleri kullanır.

Ad (kısaltma) Boyut Örnek
Kilobayt (KB) 1.024 bayt 1 KB = 1.024 bayt
Megabayt (MB) 1.0242 bayt 1 MB = 1.048.576 bayt
Gigabayt (GB) 1.0243 bayt 1 GB = 1.073.741.824 bayt

Destek istekleri

Yalnızca belgelerle ilgili sorunlar dotnet/AspNetCore.Docs deposu için uygundur. Ürün desteği için belge sorunu açmayın. Aşağıdaki destek kanallarından biri veya daha fazlası aracılığıyla yardım isteyin:

Çerçevede veya ürün geri bildirimiyle ilgili olası bir hata için, ASP.NET Core ürün birimi üzerine dotnet/aspnetcore sorun açın. Hata raporları genellikle aşağıdakileri gerektirir :

  • Sorunun net açıklaması: Sorunu açarken ürün birimi tarafından sağlanan GitHub sorun şablonundaki yönergeleri izleyin.
  • Basit bir çoğaltma projesi: Ürün birimi mühendislerinin indirip çalıştırması için GitHub'a bir proje yerleştirin. Projeyi, sorunun açılış açıklamasına çapraz bağlayın.

Bir Blazor makalesiyle ilgili olası bir sorun için bir belge sorunu açın. Belge sorununu açmak için makalenin en altındaki Belge sorunu geri bildirimi aç bağlantısını kullanın. Sorununuza eklenen meta veriler izleme verileri sağlar ve makalenin yazarına otomatik olarak ping atar. Konu, belge sorununu açmadan önce ürün birimiyle tartışıldıysa, belge sorununun açılış açıklamasına mühendislik sorununa bir çapraz bağlantı yerleştirin.

Visual Studio ile ilgili sorunlar veya geri bildirim için Visual Studio'nun içinden Sorun Bildir veya Özellik Öner hareketlerini kullanın. Bu hareketler Visual Studio'nun iç sorunlarını açar. Daha fazla bilgi için bkz. Visual Studio Geri Bildirimi.

Visual Studio Code ile ilgili sorunlar için topluluk destek forumlarında destek isteyin. Hata raporları ve ürün geri bildirimi için GitHub deposunda bir sorunmicrosoft/vscode açın.

Blazor belgelendirmesiyle ilgili GitHub sorunları, projeBlazor.Docs (dotnet/AspNetCore.Docs GitHub deposu) değerlendirme için otomatik olarak işaretlenir. Lütfen, özellikle hafta sonları ve tatillerde yanıt için lütfen kısa bir süre bekleyin. Belge yazarları hafta içi genellikle 24 saat içinde yanıt verir.

Topluluk tarafından yönetilen Blazor kaynaklara ait bağlantıların bir koleksiyonu için Awesome Blazor'u ziyaret edin.

Not

Microsoft, Awesome'a Blazor ve burada açıklanan ve bağlantılı topluluk ürün ve hizmetlerinin çoğuna sahip değildir, bakımını yapmaz veya desteklemez.