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

[アーティクル]
11/30/2023

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

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

ASP.NET Core は、.NET Core サポートポリシーに準拠しています。ライブラリでサポートする ASP.NET Core のバージョンを決定する際は、このサポートポリシーを参照してください。ライブラリは次の条件を満たす必要があります。

可能な限り、長期サポート (LTS) として分類されている ASP.NET Core バージョンをすべてサポートします。
サポート終了 (EOL) として分類されている ASP.NET Core バージョンをサポートする必要はありません。

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

ASP.NET Core 共有フレームワークの使用

.NET Core 3.0 のリリースから、多数の ASP.NET Core アセンブリがパッケージとして NuGet に公開されなくなりました。代わりに、アセンブリは Microsoft.AspNetCore.App 共有フレームワークに含まれ、.NET Core SDK およびランタイムインストーラーと共にインストールされます。公開されなくなったパッケージの一覧については、「古いパッケージ参照の削除」を参照してください。

.NET Core 3.0 から、Microsoft.NET.Sdk.Web MSBuild SDK を使用するプロジェクトは、共有フレームワークを暗黙的に参照します。 Microsoft.NET.Sdk SDK または Microsoft.NET.Sdk.Razor SDK を使用するプロジェクトで共有フレームワーク内の ASP.NET Core API を使用するには、ASP.NET Core を参照する必要があります。

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

<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.RazorSDK を使用する必要があります。

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

1 つのライブラリからサーバー側およびクライアント側のアプリによる Razor コンポーネントの使用をサポートするには、エディターに対して次の手順を使用します。

Visual Studio
Visual Studio Code / .NET CLI

Razor クラスライブラリ プロジェクトテンプレートを使用します。

Note

[サポートページとビュー] チェックボックスはオンに "しないでください"。チェックボックスをオンにすると、サーバー側アプリのみをサポートするクラスライブラリが作成されます。

統合ターミナル (VS Code) またはコマンドシェル (.NET CLI) で次のコマンドを実行します。

dotnet new razorclasslib

Note

dotnet new コマンドに -s|--support-pages-and-views オプションを追加しないでください。オプションを適用すると、サーバー側アプリのみをサポートするクラスライブラリが作成されます。

プロジェクトテンプレートから生成されたライブラリ:

インストールされている SDK に基づいて現在の .NET Framework をターゲットにします。
browser を SupportedPlatform MSBuild 項目でサポートされているプラットフォームとして含めることにより、プラットフォームの依存関係に対するブラウザーの互換性チェックを有効にします。
Microsoft.AspNetCore.Components.Web の NuGet パッケージ参照を追加します。

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

注意

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

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

ライブラリで、現在のリリースで Blazor に追加された機能と、以前のリリースを 1 つ以上をサポートする必要がある場合は、ライブラリをマルチターゲットにします。 TargetFrameworks MSBuild プロパティで、ターゲットフレームワークモニカー (TFM) のセミコロン区切りのリストを指定します。

<TargetFrameworks>{TARGET FRAMEWORKS}</TargetFrameworks>

前の例で、{TARGET FRAMEWORKS} プレースホルダーは、セミコロン区切りの TFM リストを表します。たとえば、「 netcoreapp3.1;net5.0 」のように入力します。

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

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

[ページとビューのサポート] チェックボックス (Visual Studio)、または dotnet new コマンドの -s|--support-pages-and-views オプションでライブラリが作成されるときに、ライブラリがページとビューをサポートするように指定します。
```
dotnet new razorclasslib -s
```
他の必要な MSBuild プロパティに加えて、ライブラリのプロジェクトファイル内の ASP.NET Core へのフレームワーク参照のみを指定します。
```
<ItemGroup>
  <FrameworkReference Include="Microsoft.AspNetCore.App" />
</ItemGroup>
```

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

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 を対象とする場合、次のものが必要です。

true に設定された AddRazorSupportForMvc MSBuild プロパティ。
共有フレームワークの <FrameworkReference> 要素。

Razor クラスライブラリ プロジェクトテンプレートは、.NET Core を対象とするプロジェクトについて、前述の要件を満たしています。ご使用のエディターに応じて、次の手順を使用します。

Visual Studio
Visual Studio Code / .NET CLI

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

統合ターミナル (VS Code) またはコマンドシェル (.NET CLI) で次のコマンドを実行します。

dotnet new razorclasslib -s

次に例を示します。

<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 で共有フレームワークに移動されたため、公開されなくなりました。次に例を示します。

<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> 要素を追加します。次に例を示します。

<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 パッケージは共有フレームワークに移動されたため、公開されなくなりました。次に例を示します。

<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> 要素を追加します。次に例を示します。

<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 パッケージは共有フレームワークに移動されたため、公開されなくなりました。次に例を示します。

<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 プロパティを使用してこれらのバリアントをサポートします。

<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 パッケージが追加されます。
.NET Framework 4.6.1 以降または .NET Core 2.x を対象とするコンシューマー向けに Microsoft.AspNetCore.Mvc.Razor への参照が追加されます。パッケージのバージョン 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 を対象とすることもできます。

<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、Xamarin など) で使用することはできません。
.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 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 から 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 ターゲットフレームワークシンボルで定義されたコードパスを実行します。 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
}

次のマルチターゲットプロジェクトファイルでは、このタグヘルパーのシナリオに対応しています。

<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 クライアントを追加するプロジェクトファイルは、次のようになります。

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

その他の技術情報

その他のリソース

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

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

タグヘルパー

ビューコンポーネント