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

Yayınlayan Scott Addie

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:

• Uzun Süreli 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 hissetmeyin.

ASP.NET Core'un önizleme sürümleri kullanıma sunuldukçe, aspnet/Announcements GitHub deposunda hataya neden olan değişiklikler gönderilir. Ç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ı Microsoft.AspNetCore.App ve çalışma zamanı yükleyicileriyle yüklenen 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, MSBuild SDK'sını Microsoft.NET.Sdk.Web kullanan projeler paylaşılan çerçeveye örtük olarak başvurur. veya Microsoft.NET.Sdk.Razor SDK kullanan projeler, paylaşılan çerçevede Microsoft.NET.Sdk ASP.NET Core API'lerini kullanmak için ASP.NET Core'a başvurmalıdır.

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

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

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

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

</Project>

Genişletilebilirliği dahil et Blazor

Blazorsunucu tarafı ve istemci tarafı uygulamaları için bileşen sınıf kitaplıkları oluşturmayı Razor destekler. Sınıf kitaplığındaki bileşenleri desteklemek Razor için, sınıf kitaplığıNın Microsoft.NET.Sdk'yı kullanması gerekir.Razor SDK.

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

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

Visual Studio

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ığına neden olur.

Visual Studio Code / .NET CLI

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

dotnet new razorclasslib

Not

komutuna -s|--support-pages-and-views seçeneğini eklemeyin.dotnet new 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.
• MSBuild öğesiyle SupportedPlatform desteklenen bir platform olarak ekleyerek browser platform bağımlılıkları için tarayıcı uyumluluk denetimlerini etkinleştirir.
• Microsoft.AspNetCore.Components.Web iç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 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ün etiketini seçmek için Dalları veya etiketleri değiştir açılan 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 geçerli sürüme Blazor eklenen özellikleri desteklemesi ve bir veya daha fazla önceki sürümü desteklemesi gerekiyorsa, kitaplığı çok hedefli hale getirir. MSBuild özelliğinde TargetFrameworks Hedef Çerçeve Takma Adlarının (TFM) noktalı virgülle ayrılmış bir listesini sağlayın:

<TargetFrameworks>{TARGET FRAMEWORKS}</TargetFrameworks>

Yukarıdaki örnekte yer tutucu noktalı {TARGET FRAMEWORKS} 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 CircuitHandler sunucu tarafına özgü özellikler gerektiriyorsa veya ara yazılım, MVC denetleyicileri veya Razor Sayfalar gibi temel özellikler ASP.NET kullanıyorsa, aşağıdaki yaklaşımlardan birini kullanın:Microsoft.AspNetCore.Components.Server.ProtectedBrowserStorage

• Kitaplık Destek sayfaları ve görünümleri onay kutusuyla (Visual Studio) veya komutuyla birlikte oluşturulduğunda kitaplığın -s|--support-pages-and-views sayfaları ve görünümleri desteklediğini dotnet new 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>
  

Bileşen içeren Razor kitaplıklar hakkında daha fazla bilgi için bkz. Sınıf kitaplığından Razor (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ümler 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ümler veya Razor Sayfalar

Görünümler veyaRazor Sayfalar içeren Razor bir proje Microsoft.NET.Sdk'sını kullanmalıdır.Razor SDK.

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

• AddRazorSupportForMvc MSBuild özelliği olarak ayarlanmıştırtrue.
• <FrameworkReference> Paylaşılan çerçeve için bir öğe.

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

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

Visual Studio Code / .NET CLI

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, bir Microsoft.AspNetCore.Mvc paket başvurusu gerekir. Paket Microsoft.AspNetCore.Mvc , 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ını içeren bir proje SDK'sını Microsoft.NET.Sdk kullanmalıdır. .NET Core 3.x hedefleniyorsa, paylaşılan çerçeve için bir <FrameworkReference> öğe 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) hedefleniyorsa Microsoft.AspNetCore.Mvc.Razor.. adresine bir paket başvurusu ekleyin. Paket Microsoft.AspNetCore.Mvc.Razor paylaşılan çerçeveye taşındı ve bu nedenle artık yayımlanmaz. Örneğin:

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

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

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

</Project>

Görünüm bileşenleri

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

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

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

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

</Project>

.NET Standard'ı hedef alıyorsanız (ASP.NET Core 3.x'ten önceki sürümleri desteklemek için) Microsoft.AspNetCore.Mvc.ViewFeatures'a bir paket başvurusu ekleyin. Paket Microsoft.AspNetCore.Mvc.ViewFeatures paylaşılan çerçeveye taşındı ve bu nedenle artık yayımlanmaz. Örneğin:

<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ı özelliği aracılığıyla TargetFrameworks 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:

• Paket Markdig tüm tüketiciler için eklenir.
• .NET Framework 4.6.1 veya üzerini veya .NET Core 2.x'i hedefleyen tüketiciler için Microsoft.AspNetCore.MvcRazor. başvurusu eklendi. 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. Paket Microsoft.AspNetCore.Mvc.Razor 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, UWP ve Xamarin 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 yönergelerini izleyin.
• İlgili derleme paylaşılan çerçevede yoksa her API'nin NuGet paketi için bir paket başvurusu 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 ASP.NET Core API'sinde ASP.NET Core 3.1'de hataya neden olan bir değişiklik vardır. Kitaplığın tüm sürümlerde bozuk API'yi kullanmamak için yeniden yazıp yazılamayacağını göz önünde bulundurun.

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> öğe 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 oluştuğu yerde zaman uyumlu okuma ve yazmaların etkinleştirilmesi gereken bir ara yazılım kitaplığı düşünün. Kitaplık, uygun önişlemci yönergesinde zaman uyumlu özellikleri etkinleştirmek için kodu içine almalı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:

1. Kitaplık işlevsel olarak yeni API'yi gerektiriyor mu?
2. 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> öğe 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> öğe 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 arabirimi kullanır IWebHostEnvironment . .NET Core 3.1'i hedefleyen tüketiciler, hedef çerçeve simgesi tarafından NETCOREAPP3_1 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 olarak değişir IHostingEnvironment . Bu değişiklik gerekliydi çünkü ASP.NET Core 3.1 eski olarak işaretlendi IHostingEnvironment ve değiştirilmesi önerilir IWebHostEnvironment .

[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ılan BIR API kullanma

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'sini 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 bir Razor sınıf kitaplığından (RCL) kullanma
• .NET uygulama desteği
• .NET destek ilkeleri