bir sınıf kitaplığında ASP.NET Core apı 'leri kullanma

Scott Ade tarafından

bu belge bir sınıf kitaplığında ASP.NET Core apı 'leri kullanmaya yönelik rehberlik sağlar. Diğer tüm kitaplık Kılavuzu için bkz. Açık Kaynak Kitaplığı Kılavuzu.

hangi ASP.NET Core sürümlerinin destekleyeceğini belirleme

ASP.NET Core .net Core destek ilkesineuyar. kitaplıkta hangi ASP.NET Core sürümlerinin destekleyeceği belirlenirken destek ilkesine başvurun. Bir kitaplık:

• uzun süreli destek (lts) olarak sınıflandırılan tüm ASP.NET Core sürümlerini desteklemeye yönelik bir çaba oluşturun.
• yaşam süresi (eol) olarak sınıflandırılan ASP.NET Core sürümlerini desteklemeye yönelik değildir.

ASP.NET Core önizleme sürümleri kullanılabilir hale getirilirse, aspnet/duyurular GitHub deposuna son değişiklikler gönderilir. Çerçeve özellikleri geliştirildiği için kitaplıkların Uyumluluk testi yürütülür.

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

.net Core 3,0 sürümü ile pek çok ASP.NET Core derlemesi artık paket olarak NuGet yayımlanmamıştır. Bunun yerine, derlemeler Microsoft.AspNetCore.App .NET Core SDK ve çalışma zamanı yükleyicilerle birlikte yüklenen paylaşılan çerçeveye dahil edilmiştir. Artık yayımlanmayan paketlerin listesi için bkz. artık kullanılmayan paket başvurularını kaldır.

.net Core 3,0 itibariyle, MSBuild SDK kullanan projeler, Microsoft.NET.Sdk.Web paylaşılan çerçeveye örtük olarak başvurur. veya SDK kullanan projeler, Microsoft.NET.Sdk Microsoft.NET.Sdk.Razor paylaşılan çerçevede ASP.NET Core apı 'leri kullanmak için ASP.NET Core başvurmalıdır.

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

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

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

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

</Project>

ASP.NET Core buna bu şekilde başvurulması yalnızca .net Core 3. x 'i hedefleyen projeler için desteklenir.

bir sınıf kitaplığındaki ASP.NET Core 5,0 ve üzeri apı 'leri kullanma hakkında daha fazla bilgi için bu GitHub sorunabakın.

Genişletilebilirlik dahil et Blazor

Blazor WebAssembly (ıSSTREAM) ve sunucu tabanlı barındırma modellerinidestekler. Hem barındırma modellerini desteklemede belirli bir neden olmadıkça, bir Razor bileşen Kitaplığı hem barındırma modellerini desteklemelidir. Bir Razor Bileşen kitaplığı MICROSOFT. net. SDK kullanmalıdır. Razor SDK.

Barındırma modellerini destekler

RazorVe projelerine göre bileşen tüketimini desteklemek için Blazor WebAssembly Blazor Server , düzenleyiciniz için aşağıdaki yönergeleri kullanın.

dotnet new razorclasslib

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

  <PropertyGroup>
    <TargetFramework>{TARGET FRAMEWORK}</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <SupportedPlatform Include="browser" />
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.Components.Web" Version="{VERSION}" />
  </ItemGroup>

</Project>

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

  <PropertyGroup>
    <TargetFrameworks>{TARGET FRAMEWORKS}</TargetFrameworks>
  </PropertyGroup>

  <ItemGroup>
    <SupportedPlatform Include="browser" />
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.Components.Web" Version="{VERSION}" />
  </ItemGroup>

</Project>

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

  <PropertyGroup>
    <TargetFrameworks>netstandard2.0</TargetFrameworks>
    <RazorLangVersion>3.0</RazorLangVersion>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.Components" Version="3.1.17" />
    <PackageReference Include="Microsoft.AspNetCore.Components.Web" Version="3.1.17" />
  </ItemGroup>

</Project>

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

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

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

</Project>

Bileşenleri içeren kitaplıklar hakkında daha fazla bilgi için Razor bkz Razorsınıf kitaplıklarından ASP.NET Core bileşenleri Razor kullanma ..

MVC genişletilebilirliği Ekle

Bu bölümde şunları içeren kitaplıklara ilişkin öneriler özetlenmektedir:

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

Bu bölüm, MVC 'nin birden çok sürümünü desteklemek için Çoklu hedefleme ile açıklanmamaktadır. birden çok ASP.NET Core sürümünün desteklenmesi hakkında rehberlik için bkz. çoklu ASP.NET Core sürümlerinidestekleme.

Razor görünümler veya Razor Sayfalar

Razor Görünümler veya Razor Sayfalar içeren bir projenin Microsoft. net. SDK kullanması gerekir. Razor SDK.

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

• AddRazorSupportForMvcolarak ayarlanmış bir MSBuild özelliği true .
• <FrameworkReference>Paylaşılan çerçeve için bir öğe.

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

dotnet new razorclasslib -s

Örnek:

<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 hedefliyorsa, bir Microsoft. AspNetCore. Mvc paket başvurusu gerekir. Microsoft.AspNetCore.Mvcpaket ASP.NET Core 3,0 ' de paylaşılan çerçeveye taşındı ve bu nedenle artık yayımlanmamıştır. Örnek:

<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 projenin SDK kullanması gerekir Microsoft.NET.Sdk . .NET Core 3. x ' i hedefliyorsanız, <FrameworkReference> paylaşılan çerçeve için bir öğe ekleyin. Örnek:

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

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

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

</Project>

.NET Standard hedefliyorsanız (ASP.NET Core 3. x sürümünden önceki sürümleri desteklemek için), Microsoft. aspnetcore. Mvc Razor öğesine bir paket başvurusu ekleyin. Paket Microsoft.AspNetCore.Mvc.Razor paylaşılan çerçeveye taşındı ve bu nedenle artık yayımlanıyor. Örnek:

<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

Bileşenleri görüntüle içeren bir proje SDK'yı Microsoft.NET.Sdk kullanlıdır. .NET Core 3.x'i hedeflerse, paylaşılan <FrameworkReference> çerçeve için bir öğe ekleyin. Örnek:

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

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

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

</Project>

Hedef .NET Standard (ASP.NET Core 3.x'den önceki sürümleri desteklemek için), Microsoft.AspNetCore.Mvc.ViewFeatures'abir paket başvurusu ekleyin. Paket Microsoft.AspNetCore.Mvc.ViewFeatures paylaşılan çerçeveye taşındı ve bu nedenle artık yayımlanıyor. Örnek:

<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 desteği

Birden çok farklı türü destekleyen bir kitaplık yazmanız için çoklu ASP.NET Core. Etiket Yardımcıları kitaplığının aşağıdaki farklı değişkenlerini desteklemesi gereken bir ASP.NET Core düşünün:

• ASP.NET Core 2.1 hedeflemesi .NET Framework 4.6.1
• ASP.NET Core .NET Core 2.x'i hedef alan 2.x
• ASP.NET Core .NET Core 3.x'i hedef alan 3.x

Aşağıdaki proje dosyası özelliği aracılığıyla bu varyantları TargetFrameworks 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>

Yukarıdaki proje dosyasıyla:

• Paket Markdig tüm tüketiciler için eklenir.
• Microsoft.AspNetCore.Mvc başvurusu. Razor 4.6.1 veya .NET Framework veya .NET Core 2.x'i hedef alan tüketiciler için eklenir. Paketin 2.1.0 sürümü, geriye dönük uyumluluk ASP.NET Core 2.2 ile çalışır.
• .NET Core 3.x'i hedef alan tüketiciler için paylaşılan çerçeveye başvurulmaktadır. Paket, Microsoft.AspNetCore.Mvc.Razor paylaşılan çerçeveye dahil edilir.

Alternatif olarak, .NET Standard .NET Core 2.1 ve 4.6.1 yerine .NET Framework 2.0 hedef olabilir:

<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ık yalnızca Etiket Yardımcıları içerdiği için, .NET Core ve ASP.NET Core çalışan belirli platformları hedeflemek .NET Framework. Etiket Yardımcıları Unity, UWP ve Xamarin gibi .NET Standard 2.0 uyumlu hedef çerçeveler tarafından kullanılamaz.
• .NET Standard 2.0 .NET Framework 4.7.2'de .NET Framework bazı sorunlar giderildi. .NET Framework 4.6.1'i hedefleerek .NET Framework 4.6.1 ile 4.7.1 arasında bir .NET Framework deneyimi geliştirin.

Kitaplığınız platforma özgü API'leri çağıracaksa, bu api'ler yerine belirli .NET .NET Standard. Daha fazla bilgi için bkz. Çoklu hedefleme.

Değişmemiş bir API kullanma

Imagine bir ara yazılım kitaplığını .NET Core 2.2'den 3.1'e yükselttik. Kitaplıkta ASP.NET Core ara yazılım API'leri, ASP.NET Core 2.2 ve 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ı uygulayın:

• Standart kitaplık yönergelerini izleyin.
• İlgili derleme paylaşılan çerçevede mevcut NuGet api'ler için paket başvurusu ekleyin.

Değiştirilen bir API kullanma

Imagine bir kitaplığı .NET Core 2.2'den .NET Core 3.1'e yükselterek. Kitaplıkta ASP.NET Core API'sinde 3.1'de ASP.NET Core değişiklik var. Kitaplığın tüm sürümlerde bozuk API'yi kullanmayacak şekilde yeniden yazılabilir olup olmadığını göz önünde bulundurabilirsiniz.

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

Kitaplığı yeniden yazasanız aşağıdaki adımları uygulayın:

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

Örneğin, HTTP isteği ve yanıt akışlarında zaman uyumlu okuma ve yazmalar, 3.1'den ASP.NET Core devre dışı bırakılır. ASP.NET Core 2.2 varsayılan olarak zaman uyumlu davranışı destekler. Zaman uyumlu okuma ve yazmaların, I/O'nin oluştuğu yerde etkinleştirilmesi gereken bir ara yazılım kitaplığını göz önünde bulundurabilirsiniz. Kitaplığın, uygun önişlemci yönergesinde zaman uyumlu özellikleri etkinleştirmek için kodu içine eklemesi gerekir. Örnek:

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 tanıtan bir API kullanma

Imagine 3.1'de ASP.NET Core API'sini ASP.NET Core istediğiniz. Aşağıdaki soruları göz önünde bulundurun:

1. Kitaplık işlevsel olarak yeni API'yi gerektirir mi?
2. Kitaplık bu özelliği farklı bir şekilde uygulayacak mı?

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

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

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

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

Örneğin, aşağıdaki Etiket Yardımcısı IWebHostEnvironment 3.1'de ASP.NET Core arabirimini kullanır. .NET Core 3.1'i hedef alan tüketiciler, hedef çerçeve sembolüyle tanımlanan NETCOREAPP3_1 kod yolunu yürütür. Etiket Yardımcı'sı oluşturucu parametre türü IHostingEnvironment .NET Core 2.1 ve 4.6.1 .NET Framework için olarak değişir. Bu değişiklik, 3.1 ASP.NET Core eski olarak işaretlendi ve değiştirme IHostingEnvironment olarak IWebHostEnvironment önerildi.

[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ı senaryosunu 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 kullanma

Paylaşılan çerçeveden ASP.NET Core bir derleme kullanmak için uygun paket başvurularını 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'si istemcisini eklemek için:

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

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

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

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

</Project>

Ek kaynaklar

• Kullanıcı arabirimi ile Razor sınıf kitaplıklarında yeniden ASP.NET Core
• Razorsınıf kitaplıklarından ASP.NET Core bileşenleri Razor kullanma
• .NET uygulama desteği
• .NET destek ilkeleri