Menggunakan API ASP.NET Core di pustaka kelas

Ditulis oleh Scott Addie

Dokumen ini menyediakan panduan untuk menggunakan API inti ASP.NET di pustaka kelas. Untuk semua panduan pustaka lainnya, lihat panduan pustaka sumber terbuka .

Menentukan versi ASP.NET Core mana yang akan didukung

ASP.NET Core mematuhi kebijakan dukungan .NET Core. Lihat kebijakan dukungan saat menentukan versi ASP.NET Core mana yang akan didukung di pustaka. Pustaka harus:

• Lakukan upaya untuk mendukung semua versi ASP.NET Core yang diklasifikasikan sebagai Long-Term Support (LTS).
• Tidak merasa diwajibkan untuk mendukung versi ASP.NET Core yang diklasifikasikan sebagai End of Life (EOL).

Saat rilis pratinjau ASP.NET Core tersedia, perubahan signifikan diposting di aspnet/Announcements repositori GitHub. Pengujian kompatibilitas pustaka dapat dilakukan karena fitur kerangka kerja sedang dikembangkan.

Menggunakan kerangka kerja bersama ASP.NET Core

Dengan rilis .NET Core 3.0, banyak rakitan ASP.NET Core tidak lagi diterbitkan ke NuGet sebagai paket. Sebagai gantinya, rakitan disertakan dalam kerangka kerja bersama Microsoft.AspNetCore.App, yang diinstal dengan .NET Core SDK dan penginstal runtime. Untuk daftar paket yang tidak lagi diterbitkan, lihat Menghapus referensi paket usang.

Pada .NET Core 3.0, proyek yang menggunakan Microsoft.NET.Sdk.Web MSBuild SDK secara implisit mereferensikan kerangka kerja bersama. Proyek yang menggunakan SDK Microsoft.NET.Sdk atau Microsoft.NET.Sdk.Razor harus mereferensikan ASP.NET Core untuk menggunakan API inti ASP.NET dalam kerangka kerja bersama.

Untuk mereferensikan ASP.NET Core, tambahkan elemen <FrameworkReference> berikut ke file proyek Anda:

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

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

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

</Project>

Sertakan ekstensibilitas Blazor

Blazor mendukung pengembangan pustaka kelas komponen Razor untuk aplikasi sisi server dan sisi klien. Untuk mendukung komponen Razor di pustaka kelas, pustaka kelas harus menggunakan Microsoft.NET.Sdk.Razor SDK.

Mendukung aplikasi sisi server dan sisi klien

Untuk mendukung konsumsi komponen Razor oleh aplikasi sisi server dan sisi klien dari satu pustaka, gunakan instruksi berikut untuk editor Anda.

dotnet new razorclasslib

Pustaka yang dihasilkan dari templat proyek:

• Menargetkan kerangka kerja .NET saat ini berdasarkan SDK yang diinstal.
• Mengaktifkan pemeriksaan kompatibilitas browser untuk dependensi platform dengan menyertakan browser sebagai platform yang didukung dengan item MSBuild SupportedPlatform.
• Menambahkan referensi paket NuGet untuk Microsoft.AspNetCore.Components.Web.

RazorClassLibrary-CSharp.csproj (sumber referensi)

Mendukung beberapa versi kerangka kerja

Jika pustaka harus mendukung fitur yang ditambahkan ke Blazor dalam rilis saat ini sekaligus mendukung satu atau beberapa rilis sebelumnya, targetkan pustaka ke beberapa platform. Berikan daftar Target Framework Monikers (TFM) yang dipisahkan titik koma di properti MSBuild:

<TargetFrameworks>{TARGET FRAMEWORKS}</TargetFrameworks>

Dalam contoh sebelumnya, placeholder {TARGET FRAMEWORKS} mewakili daftar TFM yang dipisahkan titik koma. Misalnya, netcoreapp3.1;net5.0.

Hanya mendukung konsumsi sisi server

Pustaka kelas jarang dibuat untuk hanya mendukung aplikasi sisi server. Jika pustaka kelas hanya memerlukan fitur khusus sisi server, seperti akses ke CircuitHandler atau Microsoft.AspNetCore.Components.Server.ProtectedBrowserStorage, atau menggunakan fitur khusus inti ASP.NET, seperti middleware, pengontrol MVC, atau Halaman Razor, gunakan satu pendekatan berikut:

• Tentukan bahwa pustaka mendukung halaman dan tampilan saat pustaka dibuat dengan halaman Dukungan dan kotak centang tampilan (Visual Studio) atau opsi -s|--support-pages-and-views dengan perintah dotnet new:

  dotnet new razorclasslib -s
  

• Hanya berikan referensi kerangka kerja ke ASP.NET Core dalam file proyek pustaka selain properti MSBuild lain yang diperlukan:

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

Untuk informasi selengkapnya tentang pustaka yang berisi komponen Razor, lihat Mengonsumsi komponen ASP.NET Core Razor dari pustaka kelas Razor (RCL).

Sertakan ekstensibilitas MVC

Bagian ini menguraikan rekomendasi untuk pustaka yang meliputi:

• Razor tampilan atau Razor Halaman
• Pembantu Tag
• Menampilkan komponen

Bagian ini tidak membahas multi-penargetan untuk mendukung beberapa versi MVC. Untuk panduan tentang mendukung beberapa versi ASP.NET Core, lihat Mendukung beberapa versi ASP.NET Core.

Razor tampilan atau Razor halaman

Proyek yang menyertakan tampilan Razor atau halaman Razor harus menggunakan Microsoft.NET.Sdk.Razor SDK.

Jika proyek menargetkan .NET Core 3.x, proyek memerlukan:

• Properti MSBuild AddRazorSupportForMvc diatur ke true.
• Elemen <FrameworkReference> untuk kerangka kerja bersama.

Templat proyek Razor Class Library memenuhi persyaratan sebelumnya untuk proyek yang menargetkan .NET Core. Gunakan instruksi berikut untuk editor Anda.

dotnet new razorclasslib -s

Misalnya:

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

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

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

</Project>

Jika proyek menargetkan .NET Standard, referensi paket Microsoft.AspNetCore.Mvc diperlukan. Paket Microsoft.AspNetCore.Mvc dipindahkan ke kerangka kerja bersama di ASP.NET Core 3.0 dan karenanya tidak lagi diterbitkan. Misalnya:

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

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

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

</Project>

Pembantu Tag

Proyek yang menyertakan Tag Helpers harus menggunakan SDK Microsoft.NET.Sdk. Jika menargetkan .NET Core 3.x, tambahkan elemen <FrameworkReference> untuk kerangka kerja bersama. Misalnya:

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

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

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

</Project>

Jika menargetkan .NET Standard (untuk mendukung versi yang lebih lama dari ASP.NET Core 3.x), tambahkan referensi paket ke Microsoft.AspNetCore.Mvc.Razor. Paket Microsoft.AspNetCore.Mvc.Razor dipindahkan ke kerangka kerja bersama dan oleh karena itu tidak lagi diterbitkan. Misalnya:

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

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

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

</Project>

Lihat komponen

Proyek yang mencakup komponen tampilan harus menggunakan SDK Microsoft.NET.Sdk. Jika menargetkan .NET Core 3.x, tambahkan elemen <FrameworkReference> untuk kerangka kerja bersama. Misalnya:

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

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

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

</Project>

Jika menargetkan .NET Standard (untuk mendukung versi yang lebih lama dari ASP.NET Core 3.x), tambahkan referensi paket ke Microsoft.AspNetCore.Mvc.ViewFeatures. Paket Microsoft.AspNetCore.Mvc.ViewFeatures dipindahkan ke kerangka kerja bersama dan oleh karena itu tidak lagi diterbitkan. Misalnya:

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

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

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

</Project>

Mendukung beberapa versi ASP.NET Core

Penargetan multi-platform diperlukan untuk mengembangkan pustaka yang mendukung beberapa varian ASP.NET Core. Pertimbangkan skenario di mana pustaka Pembantu Tag harus mendukung varian ASP.NET Core berikut:

• ASP.NET Core 2.1 yang menargetkan .NET Framework 4.6.1
• ASP.NET Core 2.x yang menargetkan .NET Core 2.x
• ASP.NET Core 3.x yang menargetkan .NET Core 3.x

File proyek berikut mendukung varian ini melalui properti TargetFrameworks:

<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>

Dengan file proyek sebelumnya:

• Paket Markdig ditambahkan untuk semua konsumen.
• Referensi ke Microsoft.AspNetCore.Mvc.Razor ditambahkan untuk konsumen yang menargetkan .NET Framework 4.6.1 atau yang lebih baru atau .NET Core 2.x. Paket versi 2.1.0 bekerja dengan ASP.NET Core 2.2 karena kompatibilitas ke belakang.
• Kerangka kerja bersama dirujuk untuk konsumen yang menargetkan .NET Core 3.x. Paket Microsoft.AspNetCore.Mvc.Razor disertakan dalam kerangka kerja bersama.

Atau, .NET Standard 2.0 dapat ditargetkan alih-alih menargetkan .NET Core 2.1 dan .NET Framework 4.6.1:

<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>

Dengan file proyek sebelumnya, peringatan berikut ada:

• Karena pustaka hanya berisi Pembantu Tag, lebih mudah untuk menargetkan platform tertentu tempat ASP.NET Core berjalan: .NET Core dan .NET Framework. Pembantu Tag tidak dapat digunakan oleh kerangka kerja target yang mematuhi .NET Standard 2.0 lainnya seperti Unity dan UWP.
• Menggunakan .NET Standard 2.0 dari .NET Framework memiliki beberapa masalah yang ditangani dalam .NET Framework 4.7.2. Anda dapat meningkatkan pengalaman bagi konsumen menggunakan .NET Framework 4.6.1 hingga 4.7.1 dengan menargetkan .NET Framework 4.6.1.

Jika pustaka Anda perlu memanggil API khusus platform, targetkan implementasi .NET tertentu alih-alih .NET Standard. Untuk informasi selengkapnya, lihat Multi-penargetan .

Menggunakan API yang belum berubah

Bayangkan skenario di mana Anda meningkatkan pustaka middleware dari .NET Core 2.2 ke 3.1. API middleware ASP.NET Core yang digunakan di pustaka belum berubah antara ASP.NET Core 2.2 dan 3.1. Untuk terus mendukung pustaka middleware di .NET Core 3.1, lakukan langkah-langkah berikut:

• Ikuti panduan pustaka standar .
• Tambahkan referensi paket untuk setiap paket NuGet API jika rakitan yang sesuai tidak ada dalam kerangka kerja bersama.

Menggunakan API yang berubah

Bayangkan skenario di mana Anda meningkatkan pustaka dari .NET Core 2.2 ke .NET Core 3.1. API ASP.NET Core yang digunakan di pustaka memiliki perubahan melanggar di ASP.NET Core 3.1. Pertimbangkan apakah pustaka dapat ditulis ulang untuk tidak menggunakan API yang rusak di semua versi.

Jika Anda dapat menulis ulang pustaka, lakukan dan terus menargetkan kerangka kerja target sebelumnya (misalnya, .NET Standard 2.0 atau .NET Framework 4.6.1) dengan referensi paket.

Jika Anda tidak dapat menulis ulang pustaka, lakukan langkah-langkah berikut:

• Tambahkan target untuk .NET Core 3.1.
• Tambahkan elemen <FrameworkReference> untuk kerangka kerja bersama.
• Gunakan direktif praproscesor #if dengan simbol kerangka kerja target yang sesuai untuk mengkompilasi kode secara kondisional.

Misalnya, pembacaan dan penulisan sinkron pada permintaan HTTP dan aliran respons dinonaktifkan secara default pada ASP.NET Core 3.1. ASP.NET Core 2.2 mendukung perilaku sinkron secara default. Pertimbangkan pustaka middleware di mana pembacaan dan penulisan sinkron harus diaktifkan ketika I/O berlangsung. Pustaka harus membungkus kode untuk mengaktifkan fitur sinkronisasi dalam direktif pra-pemrosesan yang sesuai. Misalnya:

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);
}

Menggunakan API yang diperkenalkan dalam 3.1

Bayangkan Anda ingin menggunakan ASP.NET Core API yang diperkenalkan di ASP.NET Core 3.1. Pertimbangkan pertanyaan-pertanyaan berikut:

1. Apakah pustaka secara fungsional memerlukan API baru?
2. Dapatkah pustaka menerapkan fitur ini dengan cara yang berbeda?

Jika pustaka secara fungsional memerlukan API dan tidak ada cara untuk mengimplementasikannya ke tingkat bawah:

• Dukung hanya .NET Core 3.x.
• Tambahkan elemen <FrameworkReference> untuk kerangka kerja bersama.

Jika pustaka dapat menerapkan fitur dengan cara yang berbeda:

• Tambahkan .NET Core 3.x sebagai kerangka kerja target.
• Tambahkan elemen <FrameworkReference> untuk kerangka kerja bersama.
• Gunakan direktif praproscesor #if dengan simbol kerangka kerja target yang sesuai untuk mengkompilasi kode secara kondisional.

Misalnya, Pembantu Tag berikut menggunakan antarmuka IWebHostEnvironment yang diperkenalkan di ASP.NET Core 3.1. Konsumen yang menargetkan .NET Core 3.1 menjalankan jalur kode yang ditentukan oleh simbol kerangka kerja target NETCOREAPP3_1. Jenis parameter konstruktor Pembantu Tag berubah menjadi IHostingEnvironment untuk konsumen .NET Core 2.1 dan .NET Framework 4.6.1. Perubahan ini diperlukan karena ASP.NET Core 3.1 ditandai IHostingEnvironment sebagai usang dan direkomendasikan IWebHostEnvironment sebagai pengganti.

[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
}

File proyek multi-target berikut mendukung skenario Pembantu Tag ini:

<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>

Menggunakan API yang dihapus dari kerangka kerja bersama

Untuk menggunakan rakitan ASP.NET Core yang dihapus dari kerangka kerja bersama, tambahkan referensi paket yang sesuai. Untuk daftar paket yang dihapus dari kerangka kerja bersama di ASP.NET Core 3.1, lihat Menghapus referensi paket usang.

Misalnya, untuk menambahkan klien API web:

<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>

Sumber daya tambahan

• UI Razor yang Dapat Digunakan Kembali di pustaka kelas dengan ASP.NET Core
• Menggunakan komponen Razor dari pustaka kelas Razor ASP.NET Core (RCL)
• Dukungan implementasi .NET
• kebijakan dukungan .NET