クラスライブラリでASP.NET Core APIを使用する

[アーティクル]
2025/01/18

このドキュメントでは、クラスライブラリで ASP.NET Core API を使用するためのガイダンスを提供します。その他すべてのライブラリガイダンスについては、オープンソースライブラリガイダンスのを参照してください。

サポートする ASP.NET Core のバージョンを決定する

ASP.NET Core は、.NET Core サポートポリシーに準拠しています。ライブラリでサポートするコアバージョン ASP.NET 決定するときは、サポートポリシーを参照してください。ライブラリでは、次の手順を実行する必要があります。

Long-Term サポート (LTS) として分類されているすべての ASP.NET Core バージョンをサポートするように努めます。
End of Life (EOL) として分類されるコアバージョン ASP.NET サポートする義務を感じません。

ASP.NET Core のプレビューリリースが利用可能になった時点で、aspnet/Announcements GitHub リポジトリに破壊的変更が投稿されます。ライブラリの互換性テストは、フレームワーク機能の開発中に行うことができます。

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 API を使用するために、ASP.NET Core を参照する必要があります。

Core ASP.NET 参照するには、次の <FrameworkReference> 要素をプロジェクトファイルに追加します。

XML

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

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

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

</Project>

Blazor 拡張機能を含める

では、サーバー側およびクライアント側のアプリ用のクラスライブラリコンポーネントの作成がサポートされています。クラスライブラリ Razor コンポーネントをサポートするには、クラスライブラリで microsoft.NET.Sdk を使用する必要があります。Razor SDK。

サーバー側およびクライアント側のアプリをサポートする

1 つのライブラリからのサーバー側アプリとクライアント側アプリによる 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 フレームワークをターゲットにします。
SupportedPlatform MSBuild 項目でサポートされているプラットフォームとして browser を含めることで、プラットフォームの依存関係のブラウザー互換性チェックを有効にします。
Microsoft.AspNetCore.Components.Webの NuGet パッケージ参照を追加します。

RazorClassLibrary-CSharp.csproj (参照ソース)

注意

.NET 参照ソースへのドキュメントリンクは、通常、リポジトリの既定のブランチを読み込みます。これは、.NET の次のリリースの現在の開発を表します。特定のリリースのタグを選択するには、[ブランチまたはタグの切り替え] ドロップダウンリスト を使用します。詳細については、「ASP.NET Core ソースコードのバージョンタグを選択する方法 () (dotnet/AspNetCore.Docs #26205)」を参照してください。

複数のフレームワークバージョンをサポートする

1 つ以上の以前のリリースもサポートしながら、現在のリリースの Blazor に追加された機能をライブラリでサポートする必要がある場合は、ライブラリを複数ターゲットにします。 MSBuild プロパティ TargetFrameworks 内のターゲットフレームワークモニカー (TFM) の一覧をセミコロンで区切って指定してください。

XML

<TargetFrameworks>{TARGET FRAMEWORKS}</TargetFrameworks>

前の例では、{TARGET FRAMEWORKS} プレースホルダーはセミコロンで区切られた TFM リストを表しています。たとえば、netcoreapp3.1;net5.0します。

サーバー側の使用のみをサポートする

クラスライブラリは、サーバー側アプリのみをサポートするように構築されることはほとんどありません。クラスライブラリにサーバー側固有の機能 (CircuitHandler や Microsoft.AspNetCore.Components.Server.ProtectedBrowserStorageへのアクセスなど) のみが必要な場合、またはミドルウェア、MVC コントローラー、Razor ページなどのコア固有の機能 ASP.NET 使用する場合は、次の方法 1 つの を使用します。

サポートページとビュー チェックボックス (Visual Studio) または dotnet new コマンドによる -s|--support-pages-and-views オプションを使ってライブラリを作成する際に、そのライブラリがページとビューをサポートすることを指定します。

.NET CLI
```
dotnet new razorclasslib -s
```
他の必要な MSBuild プロパティに加えて、ライブラリのプロジェクトファイル内の ASP.NET Core へのフレームワーク参照のみを指定します。

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

コンポーネントを含むライブラリの詳細については、「クラスライブラリ (RCL)から ASP.NET Core コンポーネントを使用するを参照してください。

MVC 拡張機能を含める

このセクションでは、次のようなライブラリの推奨事項について説明します。

Razor ビューまたは Razor Pages
タグヘルパー
コンポーネントを表示する

このセクションでは、複数のバージョンの MVC をサポートするマルチターゲットについては説明しません。複数の ASP.NET Core バージョンをサポートする方法については、「複数の ASP.NET Core バージョンのサポート」を参照してください。

Razor ビューまたは Razor Pages

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 クラスライブラリ プロジェクトテンプレートを使用します。このテンプレートの [Support pages and views]\(ページとビューのサポート\) チェックボックスをオンにする必要があります。

統合ターミナル (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>

(ASP.NET Core 3.x より前のバージョンをサポートするため) .NET Standard を対象とする場合は、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>

コンポーネントの表示

View コンポーネントを含むプロジェクトは、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 バリアントをサポートする必要があるシナリオを考えてみましょう。

.NET Framework 4.6.1 をターゲットとする ASP.NET Core 2.1
.NET Core 2.x をターゲットとする ASP.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 への参照。Razor は、.NET Framework 4.6.1 以降または .NET Core 2.x を対象とするコンシューマー向けに追加されます。バージョン 2.1.0 のパッケージは、下位互換性のため、ASP.NET Core 2.2 で動作します。
共有フレームワークは、.NET Core 3.x を対象とするコンシューマー向けに参照されます。 Microsoft.AspNetCore.Mvc.Razor パッケージは共有フレームワークに含まれています。

または、.NET Core 2.1 と .NET Framework 4.6.1 の両方をターゲットにするのではなく、.NET Standard 2.0 をターゲットにすることもできます。

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) をターゲットにする方が簡単です。タグヘルパーは、Unity や UWP などの他の .NET Standard 2.0 準拠ターゲットフレームワークでは使用できません。
.NET Framework から .NET Standard 2.0 を使用すると、.NET Framework 4.7.2 で対処されたいくつかの問題があります。 .NET Framework 4.6.1 をターゲットにすることで、.NET Framework 4.6.1 から 4.7.1 を使用してコンシューマーのエクスペリエンスを向上させることができます。

ライブラリでプラットフォーム固有の API を呼び出す必要がある場合は、.NET Standard ではなく特定の .NET 実装をターゲットにします。詳細については、「マルチターゲット」を参照してください。

変更されていない 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 プリプロセッサディレクティブを使用します。

たとえば、HTTP 要求ストリームと応答ストリームでの同期読み取りと書き込みは、ASP.NET Core 3.1 の時点で既定で無効になっています。 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 ターゲットフレームワークシンボルによって定義されたコードパスを実行します。タグヘルパーのコンストラクターパラメーター型が、.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
}

次の複数ターゲットプロジェクトファイルは、このタグヘルパーシナリオをサポートしています。

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 APIを使用する

サポートする ASP.NET Core のバージョンを決定する

ASP.NET Core 共有フレームワークを使用する

Blazor 拡張機能を含める

サーバー側およびクライアント側のアプリをサポートする

複数のフレームワークバージョンをサポートする

サーバー側の使用のみをサポートする

MVC 拡張機能を含める

Razor ビューまたは Razor Pages

タグ補助機能

コンポーネントの表示

複数の ASP.NET Core バージョンをサポートする

変更されていない API を使用する

変更された API を使用する

3.1 で導入された API を使用する

共有フレームワークから削除された API を使用する

その他のリソース

その他のリソース

次の方法で共有

クラスライブラリでASP.NET Core APIを使用する

サポートする ASP.NET Core のバージョンを決定する

ASP.NET Core 共有フレームワークを使用する

Blazor 拡張機能を含める

サーバー側およびクライアント側のアプリをサポートする

複数のフレームワーク バージョンをサポートする

サーバー側の使用のみをサポートする

MVC 拡張機能を含める

Razor ビューまたは Razor Pages

タグ補助機能

コンポーネントの表示

複数の ASP.NET Core バージョンをサポートする

変更されていない API を使用する

変更された API を使用する

3.1 で導入された API を使用する

共有フレームワークから削除された API を使用する

その他のリソース

その他のリソース

複数のフレームワークバージョンをサポートする