使用ガイダンス

  • [アーティクル]

Microsoft.AspNetCore.SystemWebAdapters は、ASP.NET Core で ASP.NET Framework からの動作を模倣するエミュレーション レイヤーとして使用できます。 以下に、使用時の注意事項の一部に関するいくつかのガイドラインを示します。

HttpContext の有効期間

アダプターは、要求の有効期間を過ぎると使用できない HttpContext によってサポートされています。 そのため、HttpContext は ASP.NET Core での実行時にも要求の有効期間を過ぎると使用できませんが、ASP.NET Framework では動作する場合があります。 ObjectDisposedException は、要求の終了を過ぎて使用された場合にはスローされます。

推奨事項: 必要な値を POCO に格納し、保持してください。

HttpContext への変換

HttpContext を HttpContext に変換するには、次の 2 つの方法があります。

  • 暗黙的キャスト
  • コンストラクターの使用

推奨事項: ほとんどの場合、暗黙的キャストを優先的に使用するべきです。なぜなら、これにより、作成されたインスタンスをキャッシュして、要求ごとに 1 つだけ HttpContext を確保できるからです。

CurrentCulture は既定では設定されていません

ASP.NET Framework では、CurrentCulture が要求に対して設定されましたが、これは ASP.NET Core では自動的に行われません。 代わりに、適切なミドルウェアをパイプラインに追加する必要があります。

推奨事項: これを有効にする方法の詳細については、ASP.NET Core のローカライズに関するページを参照してください。

ASP.NET Framework と同様の動作でこれを有効にする最も簡単な方法は、パイプラインに次を追加することです。

app.UseRequestLocalization();

CurrentPrincipal

ASP.NET Framework では、CurrentPrincipal と Current が現在のユーザーに設定されます。 これを ASP.NET Core ですぐに利用することはできません。 このサポートは、エンドポイントに ISetThreadCurrentPrincipal を追加すると、これらのアダプターで利用できます (SetThreadCurrentPrincipalAttribute を介してコントローラーで利用できます)。 ただし、コードをリファクタリングして使用を削除できない場合にのみ使用してください。

推奨事項: 可能であれば、代わりにプロパティの User または User を呼び出しサイトに渡して使用してください。 不可能な場合は、現在のユーザーの設定を有効にして、要求を論理シングル スレッドに設定することも検討してください (詳細については以下を参照してください)。

要求スレッドが ASP.NET Core に存在しない

ASP.NET Framework では、要求にスレッド アフィニティがあり、Current は当該のスレッドにある場合にのみ利用可能でした。 ASP.NET Core にはこうした保証がないため、Current は同一の非同期コンテキスト内で使用できますが、スレッドに関する保証は行われません。

推奨事項: HttpContext に対して読み取り/書き込みを行う場合は、シングル スレッドの手法で読み取り/書き込みを行っていることを確認する必要があります。 ISingleThreadedRequestMetadata を設定すると、要求に対し、非同期コンテキストで決して同時に実行されないようにすることを強制できます。 これはパフォーマンスに影響を与えます。また、非同時アクセスを確保するために使用をリファクタリングできない場合にのみ、使用する必要があります。 SingleThreadedRequestAttribute を使用してコントローラーに追加するために利用できる実装があります。

[SingleThreadedRequest]
public class SomeController : Controller
{
    ...
}

Request で事前のバッファリングが必要な場合

既定では、受信要求は常にシーク可能というわけでも、完全に利用可能というわけでもありません。 .NET Framework で見られる動作を取得するために、入力ストリームの事前バッファリングをオプトインできます。 これによって、受信ストリームを完全に読み取り、(設定に応じて) メモリやディスクにバッファリングします。

推奨事項: これは、IPreBufferRequestStreamMetadata インターフェイスを実装するエンドポイント メタデータを適用すると有効にできます。 これは、コントローラーやメソッドに適用可能な属性である PreBufferRequestStreamAttribute として使用できます。

すべての MVC エンドポイントでこれを有効にするために、次のように使用できる拡張メソッドがあります。

app.MapDefaultControllerRoute()
    .PreBufferRequestStream();

Response でバッファリングが必要な場合

Output、End()、Clear()、SuppressContent など、Response 上の一部の API では、出力ストリームをバッファリングすることが求められています。

推奨事項: 送信前に応答のバッファリングを必要とする Response の動作をサポートするには、IBufferResponseStreamMetadata を実装するエンドポイント メタデータを使用してエンドポイントでオプトインする必要があります。

すべての MVC エンドポイントでこれを有効にするために、次のように使用できる拡張メソッドがあります。

app.MapDefaultControllerRoute()
    .BufferResponseStream();

共有されたセッション状態

Session をサポートするには、ISessionMetadata を実装するメタデータを使用してエンドポイントでオプトインする必要があります。

推奨事項: すべての MVC エンドポイントでこれを有効にするために、次のように使用できる拡張メソッドがあります。

app.MapDefaultControllerRoute()
    .RequireSystemWebAdapterSession();

これには、セッション ストアの実装も必要です。 オプションの詳細については、こちらを参照してください。

リモート セッションでアプリケーションの追加のエンドポイントを公開する

リモート セッションのサポートでは、コア アプリでセッション情報を取得できるようにするエンドポイントを公開します。 これにより、コア アプリとフレームワーク アプリの間に長時間続く可能性のある要求が生じることがありますが、現在の要求またはセッション タイムアウト (既定では 20 分) でタイムアウトになります。

推奨事項: 使用される API キーが強力であり、フレームワーク アプリとの接続が SSL 経由で行われることを確認します。

仮想ディレクトリは、フレームワークとコア アプリケーションで同一である必要がある

仮想ディレクトリのセットアップは、ルートの生成、認可、システム内のその他のサービスに使用されます。 現時点では、ASP.NET Framework のしくみにより、異なる仮想ディレクトリを有効にする信頼性の高いメソッドは見つかりませんでした。

推奨事項: 2 つのアプリケーションが、同一のアプリケーション/仮想ディレクトリ レイアウトを持つ異なるサイト (ホストやポート) 上にあることを確認してください。