在類別庫中使用 ASP.NET Core API

文章
16/01/2025

本檔提供在類別庫中使用 ASP.NET Core API 的指引。如需所有其他連結庫指引，請參閱開放原始碼連結庫指引。

判斷要支援哪些 ASP.NET Core 版本

ASP.NET Core 遵循 .NET Core 支援原則。在判斷連結庫中要支援哪些 ASP.NET Core 版本時，請參閱支持原則。圖書館應該：

努力支援分類為 Long-Term 支援 （LTS）的所有 ASP.NET 核心版本。
不覺得有義務支援 ASP.NET 核心版本分類為 生命周期結束 （EOL）。

隨著 ASP.NET Core 的預覽版本可供使用，重大變更會張貼在 gitHub 存放庫中的 aspnet/Announcements。當開發架構功能時，可以進行連結庫的相容性測試。

使用 ASP.NET Core 共享架構

隨著 .NET Core 3.0 的發行，許多 ASP.NET Core 元件不再發佈至 NuGet 作為套件。相反地，組件會包含在與 .NET Core SDK 和執行階段安裝程式一起安裝的 Microsoft.AspNetCore.App 共用架構中。如需不再發佈的套件清單，請參閱移除過時的套件參考。

從 .NET Core 3.0 起，使用 Microsoft.NET.Sdk.Web MSBuild SDK 的專案會隱含參考共享架構。使用 Microsoft.NET.Sdk 或 Microsoft.NET.Sdk.Razor SDK 的專案必須參考 ASP.NET Core，才能在共享架構中使用 ASP.NET Core API。

若要參考 ASP.NET Core，請將下列 <FrameworkReference> 元素新增至您的項目檔：

XML

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

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

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

</Project>

包含 Blazor 擴充性

Blazor 支援在伺服器端和用戶端應用程式中建立 Razor 元件和類別庫。若要支持類別庫中的 Razor 元件，類別庫必須使用 Microsoft.NET.Sdk。Razor SDK。

支援伺服器端和用戶端應用程式

若要支援供伺服器端和用戶端應用程式從單一程式庫取用 Razor 元件，請使用以下指示。

Visual Studio
Visual Studio Code / .NET CLI

使用 Razor 類別庫 項目範本。

備註

不要選取 [支援頁面和檢視] 複選框。選取複選框會產生只支援伺服器端應用程式的類別庫。

在整合式終端機 (VS Code) 或命令提示字元 (.NET CLI) 中執行下列命令：

.NET CLI

dotnet new razorclasslib

備註

請勿將 [-s|--support-pages-and-views] 選項新增至 dotnet new 命令。套用選項會產生只支援伺服器端應用程式的類別庫。

從專案範本所產生的程式庫：

以已安裝的 SDK 為基礎的目前 .NET Framework 為目標。
啟用瀏覽器與平臺相依性的相容性檢查，藉由在 SupportedPlatform MSBuild 項目中，將 browser 納入為受支持的平臺。
為 Microsoft.AspNetCore.Components.Web新增 NuGet 套件參考。

RazorClassLibrary-CSharp.csproj （參考來源）

備註

.NET 參考來源的文件連結通常會載入存放庫的預設分支，代表下一版 .NET 的目前開發。若要選取特定版本的標籤，請使用 Switch 分支或標籤 下拉式清單。如需詳細資訊，請參閱如何選取 ASP.NET Core 原始程式碼的版本標記（dotnet/AspNetCore.Docs #26205）。

支援多個架構版本

如果程式庫必須支援在目前版本中的 Blazor 功能，並同時支援一個或多個舊版，那麼就需要多目標設計這個程式庫。在 TargetFrameworks MSBuild 屬性中提供以分號分隔的 Target Framework Monikers （TFM）列表：

XML

<TargetFrameworks>{TARGET FRAMEWORKS}</TargetFrameworks>

在上述範例中，{TARGET FRAMEWORKS} 佔位符代表分號分隔的 TFM 清單。例如，netcoreapp3.1;net5.0。

僅支援伺服器端耗用量

類別庫很少建置為僅支援伺服器端應用程式。如果類別庫只需要伺服器端特定功能，例如存取 CircuitHandler 或 Microsoft.AspNetCore.Components.Server.ProtectedBrowserStorage，或使用 ASP.NET Core 特定功能，例如中間件、MVC 控制器或 Razor 頁面，請使用以下其中一種方法：

使用 支援頁面和檢視來建立連結庫時，請使用 dotnet new 命令指定連結庫支援頁面和檢視 複選框（Visual Studio）或 [-s|--support-pages-and-views] 選項：

.NET CLI
```
dotnet new razorclasslib -s
```
除了其他所有必要的 MSBuild 屬性外，僅在程式庫的專案檔案中提供 ASP.NET Core 的框架參考：

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

如需有關包含 Razor 元件的程式庫的詳細資訊，請參閱使用來自 Razor 類別庫（RCL）的 ASP.NET Core Razor 元件。

包含MVC延展性

本節概述對圖書館的建議，包括：

Razor 檢視或 Razor 頁面
標籤協助程式
檢視元件

本節不會討論為支援多個MVC版本而進行的多重目標對應。如需支援多個 ASP.NET Core 版本的指引，請參閱支援多個 ASP.NET Core 版本。

Razor 檢視或 Razor 頁面

包含 Razor 檢視或 Razor Pages 的項目必須使用 Microsoft.NET.Sdk。Razor SDK。

如果專案以 .NET Core 3.x 為目標，則需要：

AddRazorSupportForMvc MSBuild 屬性設定為 true。
共用架構的 <FrameworkReference> 元素。

Razor 類別庫 項目範本符合以 .NET Core 為目標之專案的上述需求。請使用以下指示來操作您的編輯器。

Visual Studio
Visual Studio Code / .NET CLI

使用 Razor 類別庫 項目範本。範本的 支援頁面和檢視的 複選框應被選取。

在整合式終端機（VS Code）或命令列介面（.NET CLI）中執行下列命令：

.NET CLI

dotnet new razorclasslib -s

例如：

XML

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

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

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

</Project>

如果專案改為以 .NET Standard 為目標，則需要 Microsoft.AspNetCore.Mvc 套件參考。 Microsoft.AspNetCore.Mvc 套件已移至 ASP.NET Core 3.0 中的共享架構，因此不再發佈。例如：

XML

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

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

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

</Project>

標籤輔助工具

包含標籤協助程式的專案應該使用 Microsoft.NET.Sdk SDK。如果以 .NET Core 3.x 為目標，請為共用架構新增 <FrameworkReference> 元素。例如：

XML

<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 之前的版本），請將套件參考新增至 Microsoft.AspNetCore.Mvc。Razor。 Microsoft.AspNetCore.Mvc.Razor 套件已移至共享架構，因此不再發佈。例如：

XML

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

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

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

</Project>

檢視元件

包含檢視元件的項目應該使用 Microsoft.NET.Sdk SDK。針對 .NET Core 3.x，請為共用框架新增 <FrameworkReference> 元素。例如：

XML

<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 之前的版本），請將套件參考新增至 Microsoft.AspNetCore.Mvc.ViewFeatures。 Microsoft.AspNetCore.Mvc.ViewFeatures 套件已移至共享架構，因此不再發佈。例如：

XML

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

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

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

</Project>

支援多個 ASP.NET Core 版本

需要多重目標架構，才能撰寫支援多個 ASP.NET Core 變體的程式庫。標籤協助程式庫必須支援下列 ASP.NET Core 變體的情境：

ASP.NET Core 2.1 以 .NET Framework 4.6.1 為目標
ASP.NET Core 2.x 以 .NET Core 2.x 為目標
針對 .NET Core 3.x 的 ASP.NET Core 3.x

下列項目檔透過 TargetFrameworks 屬性支援這些變體：

XML

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

使用上述項目檔：

已為所有用戶新增 Markdig 套件。
Microsoft.AspNetCore.Mvc 的參考。針對以 .NET Framework 4.6.1 或更新版本或 .NET Core 2.x 為目標的取用者，會新增Razor。套件 2.1.0 版可以運行於 ASP.NET Core 2.2，是因為向後相容性。
針對以 .NET Core 3.x 為目標的取用者，會參考共享架構。 Microsoft.AspNetCore.Mvc.Razor 套件包含在共享架構中。

或者，.NET Standard 2.0 可以是目標，而不是以 .NET Core 2.1 和 .NET Framework 4.6.1 為目標：

XML

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

使用上述項目檔時，有下列注意事項：

由於程式庫只包含標籤協助程式，因此更容易針對 ASP.NET Core 所執行的特定平臺進行定向：.NET Core 和 .NET Framework。其他 .NET Standard 2.0 相容的目標架構無法使用標籤協助程式，例如 Unity 和 UWP。
在 .NET Framework 中使用 .NET Standard 2.0 存在一些問題，這些問題已在 .NET Framework 4.7.2 中得到解決。您可以使用 .NET Framework 4.6.1 到 4.7.1 來改善取用者的體驗，方法是以 .NET Framework 4.6.1 為目標。

如果您的程式庫需要呼叫平台特定的 API，請針對特定的 .NET 實作，而不是 .NET Standard。如需詳細資訊，請參閱多重目標設定。

使用未變更的 API

想像一下您要將中間件連結庫從 .NET Core 2.2 升級至 3.1 的案例。 ASP.NET Core 中使用在程式庫中的中間件 API 在 ASP.NET Core 2.2 和 3.1 之間沒有變化。若要繼續支援 .NET Core 3.1 中的中間件連結庫，請執行下列步驟：

請遵循標準函式庫指引。
如果對應的元件不存在於共享架構中，請為每個 API 的 NuGet 套件新增套件參考。

使用已經變更過的 API

試想一個情境，您要將程式庫從 .NET Core 2.2 升級到 .NET Core 3.1。連結庫中所使用的 ASP.NET Core API 在 ASP.NET Core 3.1 中具有重大變更。請考慮是否可以重寫程式庫，使其在所有版本中都不使用損壞的 API。

如果您可以重寫程式庫，請這樣做，並繼續以較早的目標框架（例如 .NET Standard 2.0 或 .NET Framework 4.6.1）進行目標定向，並參考套件。

如果您無法重寫程式庫，請執行以下步驟：

新增 .NET Core 3.1 的目標。
為共享架構新增 <FrameworkReference> 元素。
使用 #if 預處理器指示詞搭配適當的目標架構符號，有條件地編譯程序代碼。

例如，在 ASP.NET Core 3.1 中，HTTP 要求和響應數據流上的同步讀取和寫入預設停用。 ASP.NET Core 2.2 預設支援同步行為。請考慮一個中介軟體庫，在發生 I/O 的情況下應啟用同步讀取和寫入。函式庫應該在適當的預處理器指示詞中包裹程式碼，以啟用同步功能。例如：

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 中引進的 API

假設您想要使用 ASP.NET Core 3.1 中引進的 ASP.NET Core API。請考慮下列問題：

程式庫在功能上是否需要新的 API？
圖書館可以用不同的方法來實現這個功能嗎？

如果函式庫在功能上需要 API，而無法在較低版本中實作它：

僅以 .NET Core 3.x 為目標。
為共享架構新增 <FrameworkReference> 元素。

如果程式庫可以以不同的方式實現功能：

將 .NET Core 3.x 新增為目標架構。
為共享架構新增 <FrameworkReference> 元素。
使用 #if 預處理器指示詞搭配適當的目標架構符號，有條件地編譯程序代碼。

例如，下列標籤協助器會使用在 ASP.NET Core 3.1 中引入的 IWebHostEnvironment 介面。以 .NET Core 3.1 為目標的使用者會執行由 NETCOREAPP3_1 目標框架符號所定義的程式代碼路徑。 Tag Helper 的建構函式參數類型對於 .NET Core 2.1 及 .NET Framework 4.6.1 的使用者會更改為 IHostingEnvironment。這項變更是必要的，因為 ASP.NET Core 3.1 將 IHostingEnvironment 標示為過時，並建議 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
}

下列多目標專案檔案支援此 Tag Helper 情境：

XML

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

使用從共享架構移除的 API

若要使用已從共享架構中移除的 ASP.NET Core 元件，請新增適當的套件參考。如需從 ASP.NET Core 3.1 中從共享架構移除的套件清單，請參閱移除過時的套件參考。

例如，若要新增 Web API 用戶端：

XML

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

其他資源

在類別庫中使用 ASP.NET Core 進行可重複使用的 Razor UI 開發
從 Razor 類別庫（RCL）取用 ASP.NET Core Razor 元件
.NET 實作支援
.NET 支持原則

分享方式：