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

作成者: Scott Addie

このドキュメントでは、クラス ライブラリで 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

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

Note

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

Visual Studio Code / .NET CLI

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

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

Visual Studio Code / .NET CLI

統合ターミナル (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 を使用する必要がある場合について考えてみましょう。 以下の質問を検討します。

1. ライブラリの機能上、新しい API は必要ですか?
2. ライブラリで、この機能を別の方法で実装できますか?

ライブラリの機能上、新しい 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 のクラス ライブラリの再利用可能 Razor UI
• ASP.NET Core Razor コンポーネントを Razor クラス ライブラリ (RCL) から使用する
• .NET 実装のサポート
• .NET サポート ポリシー