Sınıf kitaplığında ASP.NET Çekirdek API'lerini kullanma

Makale
01/16/2025

Bu belge, sınıf kitaplığında ASP.NET Core API'lerini kullanmaya yönelik yönergeler sağlar. Diğer tüm kitaplık yönergeleri için bkz. Açık kaynak kitaplık kılavuzu.

Hangi ASP.NET Core sürümlerinin destekleneceğini belirleme

ASP.NET Core,.NET Core destek ilkesine bağlıdır. Kitaplıkta hangi ASP.NET Core sürümlerinin desteklenmek üzere olduğunu belirlerken destek ilkesine başvurun. Bir kitaplık şu şekilde olmalıdır:

Long-Term Destek (LTS) olarak sınıflandırılan tüm ASP.NET Core sürümlerini desteklemek için çaba sarf edin.
Kullanım Süresi Sonu (EOL) olarak sınıflandırılan ASP.NET Core sürümlerini desteklemek zorunda hissetmiyorum.

ASP.NET Core'un önizleme sürümleri yayınlandıkça, aspnet/Announcements GitHub deposunda önemli değişiklikler duyurulur. Çerçeve özellikleri geliştirilirken kitaplıkların uyumluluk testi yapılabilir.

ASP.NET Core paylaşılan çerçevesini kullanma

.NET Core 3.0 sürümüyle, birçok ASP.NET Core derlemesi artık NuGet'e paket olarak yayımlanmaz. Bunun yerine, derlemeler .NET Core SDK'sı ve çalışma zamanı yükleyicileriyle birlikte yüklenen Microsoft.AspNetCore.App paylaşılan çerçeveye dahil edilir. Artık yayımlanmamakta olan paketlerin listesi için bkz.Eski paket başvurularını kaldırma .

.NET Core 3.0 itibarıyla, Microsoft.NET.Sdk.Web MSBuild SDK'sını kullanan projeler paylaşılan çerçeveye örtük olarak başvurur. Microsoft.NET.Sdk veya Microsoft.NET.Sdk.Razor SDK'sını kullanan projelerin paylaşılan çerçevede ASP.NET Core API'lerini kullanmak için ASP.NET Core'a başvurması gerekir.

ASP.NET Core'a başvurmak için proje dosyanıza aşağıdaki <FrameworkReference> öğesini ekleyin:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>netcoreapp3.1</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>

</Project>

Blazor genişletilebilirliği dahil et

, sunucu tarafı ve istemci tarafı uygulamalar için bileşenlerini içeren sınıf kitaplıkları oluşturmayı destekler. Sınıf kitaplığındaki Razor bileşenlerini desteklemek için, sınıf kitaplığının Microsoft.NET.SdkRazor SDK'sınıkullanması gerekir.

Sunucu tarafı ve istemci tarafı uygulamalarını destekleme

Tek bir kitaplıktan sunucu tarafı ve istemci tarafı uygulamalar tarafından Razor bileşen tüketimini desteklemek için düzenleyiciniz için aşağıdaki yönergeleri kullanın.

Visual Studio
Visual Studio Code / .NET CLI

Razor Sınıf Kitaplığı proje şablonunu kullanın.

Not

Destek sayfaları ve görünümleri onay kutusunu seçmeyin. Onay kutusunun seçilmesi, yalnızca sunucu tarafı uygulamaları destekleyen bir sınıf kitaplığı oluşturur.

Tümleşik terminalde (VS Code) veya komut kabuğunda (.NET CLI) aşağıdaki komutu çalıştırın:

dotnet new razorclasslib

Not

-s|--support-pages-and-views seçeneğini dotnet new komutuna eklemeyin. Seçeneğin uygulanması, yalnızca sunucu tarafı uygulamaları destekleyen bir sınıf kitaplığına neden olur.

Proje şablonundan oluşturulan kitaplık:

Yüklü SDK'ya göre geçerli .NET çerçevesini hedefler.
SupportedPlatform MSBuild öğesiyle desteklenen bir platform olarak browser ekleyerek platform bağımlılıkları için tarayıcı uyumluluk denetimlerini etkinleştirir.
Microsoft.AspNetCore.Components.Webiçin bir NuGet paket başvurusu ekler.

RazorClassLibrary-CSharp.csproj (başvuru kaynağı)

Not

.NET başvuru kaynağına yönelik belge bağlantıları genellikle bir sonraki .NET sürümü için geçerli geliştirmeyi temsil eden deponun varsayılan dalını yükler. 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).

Birden çok çerçeve sürümünü destekleme

Kitaplığın mevcut sürümde Blazor eklenen özellikleri desteklemesi ve ayrıca bir veya daha fazla önceki sürümü desteklemesi gerekiyorsa, kitaplığı birden fazla hedefe yönlendirin. TargetFrameworks MSBuild özelliğinde noktalı virgülle ayrılmış bir Hedef Çerçeve Takma Adları (TFM) listesi sağlayın.

<TargetFrameworks>{TARGET FRAMEWORKS}</TargetFrameworks>

Yukarıdaki örnekte, {TARGET FRAMEWORKS} yer tutucusu noktalı virgülle ayrılmış TFM'ler listesini temsil eder. Örneğin, netcoreapp3.1;net5.0.

Yalnızca sunucu tarafı tüketimini destekler

Sınıf kitaplıkları nadiren yalnızca sunucu tarafı uygulamaları destekleyecek şekilde oluşturulur. Sınıf kitaplığı yalnızca veya erişimi gibi sunucu tarafına özgü özellikler gerektiriyorsa veya middleware, MVC denetleyicileri veya Sayfaları gibi ASP.NET Core'a özgü özellikler kullanıyorsa, aşağıdaki yaklaşımlardan birini kullanın:

Kitaplık Destek sayfaları ve görünümleri onay kutusuyla (Visual Studio) veya dotnet new komutuyla -s|--support-pages-and-views seçeneğiyle oluşturulduğunda kitaplığın sayfaları ve görünümleri desteklediğini belirtin:
```
dotnet new razorclasslib -s
```
Diğer gerekli MSBuild özelliklerine ek olarak yalnızca kitaplığın proje dosyasındaki ASP.NET Core'a çerçeve başvurusu sağlayın:
```
<ItemGroup>
  <FrameworkReference Include="Microsoft.AspNetCore.App" />
</ItemGroup>
```

Razor bileşenleri içeren kitaplıklar hakkında daha fazla bilgi için bkz. Razor sınıf kitaplığından (RCL)ASP.NET Core Razor bileşenlerini kullanma.

MVC genişletilebilirliğini dahil et

Bu bölümde, aşağıdaki kitaplıklar için öneriler özetlenir:

Razor görünümleri veya Razor Sayfaları
Etiket Yardımcıları
Görünüm bileşenleri

Bu bölümde, MVC'nin birden çok sürümünü desteklemek için çoklu hedefleme ele alınmıyor. Birden çok ASP.NET Core sürümünü destekleme hakkında yönergeler için bkz. Birden çok ASP.NET Core sürümünü destekleme.

Razor Görünüm veya Razor Sayfa

Razor görünümlerini veya Razor Sayfaları içeren bir proje Microsoft.NET.Sdk. SDKRazor kullanmalıdır.

Proje .NET Core 3.x'i hedeflerse, şunları gerektirir:

Bir AddRazorSupportForMvc MSBuild özelliği trueolarak ayarlanmış.
Paylaşılan çerçeve için bir <FrameworkReference> öğesi.

Razor Sınıf Kitaplığı proje şablonu, .NET Core'a yönelik projeler için önceki gereksinimleri karşılar. Düzenleyiciniz için aşağıdaki yönergeleri kullanın.

Visual Studio
Visual Studio Code / .NET CLI

Razor Sınıf Kitaplığı proje şablonunu kullanın. Şablonun "Destek sayfaları ve görünümleri" onay kutusu seçilmelidir.

Tümleşik terminalde (VS Code) veya komut kabuğunda (.NET CLI) aşağıdaki komutu çalıştırın:

dotnet new razorclasslib -s

Örneğin:

<Project Sdk="Microsoft.NET.Sdk.Razor">

  <PropertyGroup>
    <TargetFramework>netcoreapp3.1</TargetFramework>
    <AddRazorSupportForMvc>true</AddRazorSupportForMvc>
  </PropertyGroup>

  <ItemGroup>
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>

</Project>

Proje bunun yerine .NET Standard'ı hedeflerse, Microsoft.AspNetCore.Mvc paket başvurusu gerekir. Microsoft.AspNetCore.Mvc paketi ASP.NET Core 3.0'da paylaşılan çerçeveye taşındı ve bu nedenle artık yayımlanmaz. Örneğin:

<Project Sdk="Microsoft.NET.Sdk.Razor">

  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.Mvc" Version="2.2.0" />
  </ItemGroup>

</Project>

Etiket Yardımcıları

Etiket Yardımcıları içeren bir proje Microsoft.NET.Sdk SDK'sını kullanmalıdır. .NET Core 3.x hedefleniyorsa, paylaşılan çerçeve için bir <FrameworkReference> öğesi ekleyin. Örneğin:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>netcoreapp3.1</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>

</Project>

.NET Standard'ı (ASP.NET Core 3.x'ten önceki sürümleri desteklemek için) hedefliyorsanız, Microsoft.AspNetCore.Mvc'e bir paket başvurusu ekleyin.Razor. Microsoft.AspNetCore.Mvc.Razor paketi paylaşılan çerçeveye taşındı ve bu nedenle artık yayımlanmaz. Mesela:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.Mvc" Version="2.2.0" />
  </ItemGroup>

</Project>

Bileşenleri görüntüleme

Görünüm bileşenlerini içeren bir projeMicrosoft.NET.Sdk SDK'sını kullanmalıdır. .NET Core 3.x hedefleniyorsa, paylaşılan çerçeve için bir <FrameworkReference> öğesi ekleyin. Mesela:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>netcoreapp3.1</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>

</Project>

.NET Standard'ı hedeflemek (ASP.NET Core 3.x'ten önceki sürümleri desteklemek için) amacıyla, Microsoft.AspNetCore.Mvc.ViewFeaturesadlı pakete bir başvuru ekleyin. Microsoft.AspNetCore.Mvc.ViewFeatures paketi paylaşılan çerçeveye taşındı ve bu nedenle artık yayımlanmaz. Mesela:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.Mvc.ViewFeatures" Version="2.2.0" />
  </ItemGroup>

</Project>

Birden çok ASP.NET Core sürümünü destekleme

birden çok ASP.NET Core değişkenini destekleyen bir kitaplık yazmak için çoklu hedefleme gereklidir. Etiket Yardımcıları kitaplığının aşağıdaki ASP.NET Core değişkenlerini desteklemesi gereken bir senaryo düşünün:

.NET Framework 4.6.1'i hedefleyen ASP.NET Core 2.1
.NET Core 2.x'i hedefleyen ASP.NET Core 2.x
.NET Core 3.x'i hedefleyen ASP.NET Core 3.x

Aşağıdaki proje dosyası, TargetFrameworks özelliği aracılığıyla bu varyantları destekler:

<Project Sdk="Microsoft.NET.Sdk">
  
  <PropertyGroup>
    <TargetFrameworks>netcoreapp2.1;netcoreapp3.1;net461</TargetFrameworks>
  </PropertyGroup>
  
  <ItemGroup>
    <PackageReference Include="Markdig" Version="0.16.0" />
  </ItemGroup>
  
  <ItemGroup Condition="'$(TargetFramework)' != 'netcoreapp3.1'">
    <PackageReference Include="Microsoft.AspNetCore.Mvc.Razor" Version="2.1.0" />
  </ItemGroup>

  <ItemGroup Condition="'$(TargetFramework)' == 'netcoreapp3.1'">
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>
</Project>

Önceki proje dosyasıyla:

Markdig paketi tüm tüketiciler için eklenir.
Microsoft.AspNetCore.Mvc başvurusu. .NET Framework 4.6.1 veya üzerini veya .NET Core 2.x'i hedefleyen tüketiciler içinRazor eklenmiştir. Paketin 2.1.0 sürümü geriye dönük uyumluluk nedeniyle ASP.NET Core 2.2 ile çalışır.
.NET Core 3.x'i hedefleyen tüketiciler için paylaşılan çerçeveye başvurulur. Microsoft.AspNetCore.Mvc.Razor paketi paylaşılan çerçeveye dahil edilir.

Alternatif olarak, .NET Core 2.1 ve .NET Framework 4.6.1 hedeflenmek yerine .NET Standard 2.0 hedeflenebilir:

<Project Sdk="Microsoft.NET.Sdk">
  
  <PropertyGroup>
    <TargetFrameworks>netstandard2.0;netcoreapp3.1</TargetFrameworks>
  </PropertyGroup>
  
  <ItemGroup>
    <PackageReference Include="Markdig" Version="0.16.0" />
  </ItemGroup>
  
  <ItemGroup Condition="'$(TargetFramework)' != 'netcoreapp3.1'">
    <PackageReference Include="Microsoft.AspNetCore.Mvc.Razor" Version="2.1.0" />
  </ItemGroup>

  <ItemGroup Condition="'$(TargetFramework)' == 'netcoreapp3.1'">
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>
</Project>

Yukarıdaki proje dosyasında aşağıdaki uyarılar vardır:

Kitaplıkta yalnızca Etiket Yardımcıları bulunduğundan, ASP.NET Core'un çalıştığı belirli platformları hedeflemek daha kolaydır: .NET Core ve .NET Framework. Etiket Yardımcıları Unity ve UWP gibi diğer .NET Standard 2.0 uyumlu hedef çerçeveler tarafından kullanılamaz.
.NET Framework'ten .NET Standard 2.0 kullanıldığında .NET Framework 4.7.2'de giderilen bazı sorunlar vardır. .NET Framework 4.6.1 ile 4.7.1 arasında .NET Framework 4.6.1'i hedefleyerek tüketiciler için deneyimi geliştirebilirsiniz.

Kitaplığınızın platforma özgü API'leri çağırması gerekiyorsa.NET Standard yerine belirli .NET uygulamalarını hedefleyin. Daha fazla bilgi için bkz. çoklu hedefleme.

Değişmemiş bir API kullanma

Bir ara yazılım kitaplığını .NET Core 2.2'den 3.1'e yükselttiğiniz bir senaryo düşünün. Kitaplıkta kullanılan ASP.NET Core ara yazılım API'leri, ASP.NET Core 2.2 ile 3.1 arasında değişmemiştir. .NET Core 3.1'de ara yazılım kitaplığını desteklemeye devam etmek için aşağıdaki adımları izleyin:

standart kitaplık kılavuzunu izleyin.
Paylaşılan çerçevede ilgili derleme mevcut değilse, her API'nin NuGet paketi için bir paket referansı ekleyin.

Değişen bir API kullanma

Kitaplığı .NET Core 2.2'den .NET Core 3.1'e yükselttiğiniz bir senaryo düşünün. Kitaplıkta kullanılan bir ASP.NET Core API'sinin ASP.NET Core 3.1'de hataya neden olan değişiklik vardır. Kitaplığın tüm sürümlerde bozuk API'yi kullanmamak için yeniden yazılıp yazılamayacağını değerlendirin.

Kitaplığı yeniden yazabiliyorsanız, bunu yapın ve paket başvurularıyla önceki bir hedef çerçeveyi (örneğin, .NET Standard 2.0 veya .NET Framework 4.6.1) hedeflemeye devam edin.

Kitaplığı yeniden yazamıyorsanız aşağıdaki adımları izleyin:

.NET Core 3.1 için bir hedef ekleyin.
Paylaşılan çerçeve için bir <FrameworkReference> öğesi ekleyin.
Kodu koşullu olarak derlemek için uygun hedef çerçeve simgesiyle #if önişlemci yönergesini kullanın.

Örneğin HTTP isteği ve yanıt akışlarında zaman uyumlu okuma ve yazma işlemleri, ASP.NET Core 3.1 itibarıyla varsayılan olarak devre dışı bırakılır. ASP.NET Core 2.2, zaman uyumlu davranışı varsayılan olarak destekler. G/Ç'nin yapıldığı yerlerde zaman uyumlu okuma ve yazmaların etkinleştirilmesi gereken bir ara katman kütüphanesi düşünün. Kütüphane, eşzamanlı özellikleri etkinleştirmek için kodu uygun önişlemci yönergesine koymalıdır. Örneğin:

public async Task Invoke(HttpContext httpContext)
{
    if (httpContext.Request.Path.StartsWithSegments(_path, StringComparison.Ordinal))
    {
        httpContext.Response.StatusCode = (int) HttpStatusCode.OK;
        httpContext.Response.ContentType = "application/json";
        httpContext.Response.ContentLength = _bufferSize;

#if !NETCOREAPP3_1 && !NETCOREAPP5_0
        var syncIOFeature = httpContext.Features.Get<IHttpBodyControlFeature>();
        if (syncIOFeature != null)
        {
            syncIOFeature.AllowSynchronousIO = true;
        }

        using (var sw = new StreamWriter(
            httpContext.Response.Body, _encoding, bufferSize: _bufferSize))
        {
            _json.Serialize(sw, new JsonMessage { message = "Hello, World!" });
        }
#else
        await JsonSerializer.SerializeAsync<JsonMessage>(
            httpContext.Response.Body, new JsonMessage { message = "Hello, World!" });
#endif
        return;
    }

    await _next(httpContext);
}

3.1'de kullanıma sunulan bir API kullanma

ASP.NET Core 3.1'de tanıtılan bir ASP.NET Core API'sini kullanmak istediğinizi düşünün. Aşağıdaki soruları göz önünde bulundurun:

Kitaplık işlevsel olarak yeni API'yi gerektiriyor mu?
Kitaplık bu özelliği farklı bir şekilde uygulayabilir mi?

Kitaplık API'yi işlevsel olarak gerektiriyorsa ve bunu alt düzeyde uygulamanın hiçbir yolu yoksa:

Yalnızca .NET Core 3.x'i hedefle.
Paylaşılan çerçeve için bir <FrameworkReference> öğesi ekleyin.

Kitaplık özelliği farklı bir şekilde uygulayabiliyorsa:

Hedef çerçeve olarak .NET Core 3.x'i ekleyin.
Paylaşılan çerçeve için bir <FrameworkReference> öğesi ekleyin.
Kodu koşullu olarak derlemek için uygun hedef çerçeve simgesiyle #if önişlemci yönergesini kullanın.

Örneğin, aşağıdaki Etiket Yardımcısı ASP.NET Core 3.1'de tanıtılan IWebHostEnvironment arabirimini kullanır. .NET Core 3.1'i hedefleyen tüketiciler, NETCOREAPP3_1 hedef çerçeve simgesi tarafından tanımlanan kod yolunu yürütür. Etiket Yardımcısı'nın oluşturucu parametre türü .NET Core 2.1 ve .NET Framework 4.6.1 tüketicileri için IHostingEnvironment olarak değişir. ASP.NET Core 3.1 IHostingEnvironment eski olarak işaretlendiğinden ve değiştirme olarak IWebHostEnvironment önerildiğinden bu değişiklik gerekliydi.

[HtmlTargetElement("script", Attributes = "asp-inline")]
public class ScriptInliningTagHelper : TagHelper
{
    private readonly IFileProvider _wwwroot;

#if NETCOREAPP3_1
    public ScriptInliningTagHelper(IWebHostEnvironment env)
#else
    public ScriptInliningTagHelper(IHostingEnvironment env)
#endif
    {
        _wwwroot = env.WebRootFileProvider;
    }

    // code omitted for brevity
}

Aşağıdaki çok hedefli proje dosyası bu Etiket Yardımcısı senaryoyu destekler:

<Project Sdk="Microsoft.NET.Sdk">
  
  <PropertyGroup>
    <TargetFrameworks>netcoreapp2.1;netcoreapp3.1;net461</TargetFrameworks>
  </PropertyGroup>
  
  <ItemGroup>
    <PackageReference Include="Markdig" Version="0.16.0" />
  </ItemGroup>
  
  <ItemGroup Condition="'$(TargetFramework)' != 'netcoreapp3.1'">
    <PackageReference Include="Microsoft.AspNetCore.Mvc.Razor" Version="2.1.0" />
  </ItemGroup>

  <ItemGroup Condition="'$(TargetFramework)' == 'netcoreapp3.1'">
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>
</Project>

Paylaşılan çerçeveden kaldırılmış bir API kullanın

Paylaşılan çerçeveden kaldırılan bir ASP.NET Core derlemesi kullanmak için uygun paket başvuruyu ekleyin. ASP.NET Core 3.1'de paylaşılan çerçeveden kaldırılan paketlerin listesi için bkz. Eski paket başvurularını kaldırma.

Örneğin, web API istemcisini eklemek için:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net6.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNet.WebApi.Client" Version="5.2.7" />
  </ItemGroup>

</Project>

Ek kaynaklar

ASP.NET Core ile sınıf kitaplıklarında yeniden kullanılabilir Razor kullanıcı arabirimi
ASP.NET Core Razor bileşenlerini Razor sınıf kitaplığından (RCL) kullanma
.NET uygulama desteği
.NET destek ilkeleri

Aracılığıyla paylaş

Sınıf kitaplığında ASP.NET Çekirdek API'lerini kullanma

Hangi ASP.NET Core sürümlerinin destekleneceğini belirleme

ASP.NET Core paylaşılan çerçevesini kullanma

Blazor genişletilebilirliği dahil et

Sunucu tarafı ve istemci tarafı uygulamalarını destekleme

Birden çok çerçeve sürümünü destekleme

Yalnızca sunucu tarafı tüketimini destekler

MVC genişletilebilirliğini dahil et

Razor Görünüm veya Razor Sayfa

Etiket Yardımcıları

Bileşenleri görüntüleme

Birden çok ASP.NET Core sürümünü destekleme

Değişmemiş bir API kullanma

Değişen bir API kullanma

3.1'de kullanıma sunulan bir API kullanma

Paylaşılan çerçeveden kaldırılmış bir API kullanın

Ek kaynaklar

Ek kaynaklar