Menggunakan API ASP.NET Core di pustaka kelas

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 Dukungan Jangka Panjang (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 yang melanggar diposting di repositori GitHub aspnet/Pengumuman . 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. Sebaliknya, rakitan disertakan dalam Microsoft.AspNetCore.App kerangka kerja bersama, 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 Microsoft.NET.Sdk atau Microsoft.NET.Sdk.Razor SDK harus mereferensikan ASP.NET Core untuk menggunakan API ASP.NET Core dalam kerangka kerja bersama.

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

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

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

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

</Project>

Sertakan Blazor ekstensibilitas

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

Mendukung aplikasi sisi server dan sisi klien

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

Visual Studio

Razor Gunakan templat proyek Pustaka Kelas.

Catatan

Jangan pilih kotak centang Halaman dukungan dan tampilan. Memilih kotak centang menghasilkan pustaka kelas yang hanya mendukung aplikasi sisi server.

Visual Studio Code / .NET CLI

Jalankan perintah berikut di terminal terintegrasi (VS Code) atau shell perintah (.NET CLI):

dotnet new razorclasslib

Catatan

Jangan tambahkan -s|--support-pages-and-views opsi ke dotnet new perintah . Menerapkan opsi menghasilkan pustaka kelas yang hanya mendukung aplikasi sisi server.

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 SupportedPlatform item MSBuild.
• Menambahkan referensi paket NuGet untuk Microsoft.AspNetCore.Components.Web.

RazorClassLibrary-CSharp.csproj (sumber referensi)

Catatan

Tautan dokumentasi ke sumber referensi .NET biasanya memuat cabang default repositori, yang mewakili pengembangan saat ini untuk rilis .NET berikutnya. Untuk memilih tag rilis tertentu, gunakan daftar dropdown Beralih cabang atau tag. Untuk informasi lebih lanjut, lihat Cara memilih tag versi kode sumber ASP.NET Core (dotnet/AspNetCore.Docs #26205).

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, multi-target pustaka. Berikan daftar Moniker Kerangka Kerja Target (TFM) yang dipisahkan titik koma di TargetFrameworks properti MSBuild:

<TargetFrameworks>{TARGET FRAMEWORKS}</TargetFrameworks>

Dalam contoh sebelumnya, {TARGET FRAMEWORKS} tempat penampung mewakili daftar TFM yang dipisahkan titik koma. Contohnya,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 ASP.NET Core, seperti middleware, pengontrol MVC, atau Razor Halaman, gunakan salah satu pendekatan berikut:

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

  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 Razor komponen, lihat Mengonsumsi komponen ASP.NET Core Razor dari Razor pustaka kelas (RCL).

Sertakan ekstensibilitas MVC

Bagian ini menguraikan rekomendasi untuk pustaka yang meliputi:

• Razor tampilan atau Razor Halaman
• Tag Helper
• Lihat 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 Razor tampilan atau Razor Halaman harus menggunakan Microsoft.NET.Sdk.Razor SDK.

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

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

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

Visual Studio

Razor Gunakan templat proyek Pustaka Kelas. Kotak centang Halaman dukungan dan tampilan templat harus dipilih.

Visual Studio Code / .NET CLI

Jalankan perintah berikut di terminal terintegrasi (VS Code) atau shell perintah (.NET CLI):

dotnet new razorclasslib -s

Contohnya:

<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. Contohnya:

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

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

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

</Project>

Tag Helper

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

<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. Contohnya:

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

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

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

</Project>

Melihat komponen

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

<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. Contohnya:

<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

Multi-penargetan diperlukan untuk menulis 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 TargetFrameworks properti :

<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 berfungsi dengan ASP.NET Core 2.2 karena kompatibilitas mundur.
• 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, UWP, dan Xamarin.
• Menggunakan .NET Standard 2.0 dari .NET Framework memiliki beberapa masalah yang ditangani di .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 yang melanggar dalam 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.
• <FrameworkReference> Tambahkan elemen untuk kerangka kerja bersama.
• Gunakan direktif pra-prosesor #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 tempat baca dan tulis sinkron harus diaktifkan di mana I/O terjadi. Pustaka harus mengapit kode untuk mengaktifkan fitur sinkron dalam direktif pra-prosesor yang sesuai. Contohnya:

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:

• Target .NET Core 3.x saja.
• <FrameworkReference> Tambahkan elemen untuk kerangka kerja bersama.

Jika pustaka dapat menerapkan fitur dengan cara yang berbeda:

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

Misalnya, Pembantu Tag berikut menggunakan antarmuka yang IWebHostEnvironment diperkenalkan di ASP.NET Core 3.1. Konsumen yang menargetkan .NET Core 3.1 menjalankan jalur kode yang ditentukan oleh NETCOREAPP3_1 simbol kerangka kerja target. 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:

• Antarmuka pengguna Razor yang dapat digunakan kembali di pustaka kelas dengan ASP.NET Core
• Menggunakan komponen Razor ASP.NET Core dari pustaka kelas Razor (RCL)
• Dukungan implementasi .NET
• Kebijakan dukungan .NET