ASP.NET Core 2.1 から 2.2 への移行

  • [アーティクル]

作成者: Scott Addie

この記事では、既存の ASP.NET Core 2.1 プロジェクトを ASP.NET Core 2.2 に更新する方法について説明します。

前提条件

警告

Visual Studio 2017 を使用している場合、Visual Studio で動作しない .NET Core SDK のバージョンについては、dotnet/sdk issue #3124 を参照してください。

ターゲット フレームワーク モニカー (TFM) の更新

.NET Core をターゲットとするプロジェクトでは、.NET Core 2.2 以上のバージョンの TFM を使用する必要があります。 プロジェクト ファイル内で、netcoreapp2.2が含まれる <TargetFramework> ノードの内部テキストを更新します。

<TargetFramework>netcoreapp2.2</TargetFramework>

.NET Framework をターゲットとするプロジェクトでは、.NET Framework 4.6.1 以上の TFM バージョンを引き続き使用する場合があります。

<TargetFramework>net461</TargetFramework>

IIS インプロセス ホスティング モデルを採用する

IIS のインプロセス ホスティング モデルを採用するには、値が InProcess の <AspNetCoreHostingModel> プロパティを、プロジェクト ファイルの <PropertyGroup> に追加します。

<AspNetCoreHostingModel>InProcess</AspNetCoreHostingModel>

.NET Framework をターゲットとする ASP.NET Core アプリでは、インプロセス ホスティング モデルはサポートされていません。

詳細については、IIS の ASP.NET Core モジュール (ANCM) に関するページを参照してください。

カスタム web.config ファイルを更新する

プロジェクト ルートのカスタム web.config ファイルを使用して、発行済み web.config ファイルを生成するプロジェクトでは、次の操作を行います。

  • ASP.NET Core モジュール (name="aspNetCore") が追加されている <handlers> エントリ内で、modules 属性の値を AspNetCoreModule から AspNetCoreModuleV2 に変更します。
  • <aspNetCore> 要素内で、ホスティング モデル属性 (hostingModel="InProcess") を追加します。

web.config ファイルの詳細と例については、「IIS の ASP.NET Core モジュール (ANCM)」を参照してください。

パッケージ参照の更新

.NET Core をターゲットとする場合は、プロジェクト ファイル内にあるメタパッケージ参照の Version 属性を削除します。 Version 属性を含めると、次の警告が表示されます。

A PackageReference to 'Microsoft.AspNetCore.App' specified a Version of `2.2.0`. Specifying the version of this package is not recommended. For more information, see https://aka.ms/sdkimplicitrefs

詳細については、「ASP.NET Core の Microsoft.AspNetCore.App メタパッケージ」を参照してください。

メタパッケージ参照は、次の <PackageReference /> ノードに似ています。

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

.NET Framework をターゲットとする場合は、各パッケージ参照の Version 属性を 2.2.0 以降に更新します。 次に示すのは、.NET Framework をターゲットとする、一般的な ASP.NET Core 2.2 プロジェクトのパッケージ参照です。

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

Microsoft.AspNetCore.Razor.Design パッケージを参照している場合は、その Version 属性を 2.2.0 以降に更新します。 この操作を行わないと、次のエラーが発生します。

Detected package downgrade: Microsoft.AspNetCore.Razor.Design from 2.2.0 to 2.1.2. Reference the package directly from the project to select a different version.

global.json での .NET Core SDK バージョンの更新

使用するソリューションが global.json ファイルに依存して、特定の .NET Core SDK バージョンをターゲットにしている場合、その version プロパティを、コンピューターにインストールされている 2.2 バージョンに更新します。

{
  "sdk": {
    "version": "2.2.100"
  }
}

起動設定を更新する

Visual Studio Code を使用している場合は、プロジェクトの起動設定ファイル (.vscode/launch.json) を更新します。 program パスでは、新しい TFM を参照する必要があります。

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": ".NET Core Launch (web)",
            "type": "coreclr",
            "request": "launch",
            "preLaunchTask": "build",
            "program": "${workspaceFolder}/bin/Debug/netcoreapp2.2/test-app.dll",
            "args": [],
            "cwd": "${workspaceFolder}",
            "stopAtEntry": false,
            "internalConsoleOptions": "openOnSessionStart",
            "launchBrowser": {
                "enabled": true,
                "args": "${auto-detect-url}",
                "windows": {
                    "command": "cmd.exe",
                    "args": "/C start ${auto-detect-url}"
                },
                "osx": {
                    "command": "open"
                },
                "linux": {
                    "command": "xdg-open"
                }
            },
            "env": {
                "ASPNETCORE_ENVIRONMENT": "Development"
            },
            "sourceFileMap": {
                "/Views": "${workspaceFolder}/Views"
            }
        },
        {
            "name": ".NET Core Attach",
            "type": "coreclr",
            "request": "attach",
            "processId": "${command:pickProcess}"
        }
    ]
}

Kestrel 構成を更新する

アプリで Program クラスの CreateWebHostBuilder メソッド内にある CreateDefaultBuilder を呼び出して、UseKestrel を呼び出す場合、IIS インプロセス ホスティング モデルとの競合を回避するには、UseKestrel ではなく、ConfigureKestrel を呼び出して、Kestrel サーバーを構成します。

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureKestrel((context, options) =>
        {
            // Set properties and call methods on options
        });

アプリで CreateDefaultBuilder を呼び出さず、Program クラスでホストを手動でビルドする場合は、ConfigureKestrel を呼び出す前に、UseKestrel を呼び出します。

public static void Main(string[] args)
{
    var host = new WebHostBuilder()
        .UseContentRoot(Directory.GetCurrentDirectory())
        .UseKestrel()
        .UseIISIntegration()
        .UseStartup<Startup>()
        .ConfigureKestrel((context, options) =>
        {
            // Set properties and call methods on options
        })
        .Build();

    host.Run();
}

詳細については、「ASP.NET Core の Kestrel Web サーバー」を参照してください。

互換バージョンを更新する

Startup.ConfigureServices の互換バージョンを Version_2_2 に更新します。

services.AddMvc()
        .SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

CORS ポリシーを更新する

ポリシーによって任意のオリジンが許可され、資格情報が許可される場合、ASP.NET Core 2.2 では、CORS ミドルウェアがワイルドカード オリジン (*) で応答します。 ワイルドカード オリジン (*) が指定されている場合、視覚情報はサポートされません。また、ブラウザーでは、CORS 要求が許可されません。 クライアントの問題を解決するためのオプションなどの詳細については、MDN Web ドキュメントを参照してください。

サーバーでこの問題を解決するには、次のいずれかの操作を実行します。

  • CORS ポリシーを変更して、資格情報を許可しないようにします。 つまり、ポリシーを構成するときに、AllowCredentials への呼び出しを削除します。
  • CORS 要求を正常に実行するために資格情報が必要な場合は、許可されているホストを指定するようにポリシーを変更します。 たとえば、AllowAnyOrigin を使用する代わりに、builder.WithOrigins("https://api.example1.com", "https://example2.com") を使用します。

Docker イメージの更新

次の表では、Docker イメージ タグの変更を示します。

2.1 2.2
microsoft/dotnet:2.1-aspnetcore-runtime mcr.microsoft.com/dotnet/core/aspnet:2.2
microsoft/dotnet:2.1-sdk mcr.microsoft.com/dotnet/core/sdk:2.2

前の表の 2.2 の列で新しいイメージ タグを使用するには、Dockerfile で FROM の行を変更します。

IIS インプロセス ホスティング使用時に Visual Studio で手動でビルドする

Visual Studio のブラウザー要求時の自動ビルド エクスペリエンスは、IIS インプロセス ホスティング モデルでは機能しません。 インプロセス ホスティングを使用する場合は、プロジェクトを手動でリビルドする必要があります。 このエクスペリエンスの向上は、Visual Studio の今後のリリースで予定されています。

ログ コードを更新する

推奨されるログ構成コードは、2.1 から 2.2 で変更はありませんでしたが、2.1 で機能していた一部の 1.x コード パターンが、2.2 では機能しなくなりました。

アプリによって、Startup クラス内でログ プロバイダーの初期化、フィルター処理、構成の読み込みが行われる場合は、そのコードを Program.Main に移動します。

  • プロバイダーの初期化:

    1.x の例:

    public void Configure(IApplicationBuilder app, ILoggerFactory loggerFactory)
{
    loggerFactory.AddConsole();
}

    2.2 の例:

    
public static void Main(string[] args)
{
    var webHost = new WebHostBuilder()
        // ...
        .ConfigureLogging((hostingContext, logging) =>
        {
            logging.AddConsole();
        })
        // ...
}

  • フィルター処理する:

    1.x の例:

    public void Configure(IApplicationBuilder app, ILoggerFactory loggerFactory)
{
    loggerFactory.AddConsole(LogLevel.Information);
    // or
    loggerFactory.AddConsole((category, level) => 
        category == "A" || level == LogLevel.Critical);
}

    2.2 の例:

    public static void Main(string[] args)
{
    var webHost = new WebHostBuilder()
        // ...
        .ConfigureLogging((hostingContext, logging) =>
        {
            logging.AddConsole()
                   .AddFilter<ConsoleLoggerProvider>
                       (category: null, level: LogLevel.Information)
                   // or
                   .AddFilter<ConsoleLoggerProvider>
                       ((category, level) => category == "A" ||
                           level == LogLevel.Critical)
            );
        })
        // ...
}

  • 構成の読み込み:

    1.x の例:

    public void Configure(IApplicationBuilder app, ILoggerFactory loggerFactory)
{
    loggerFactory.AddConsole(Configuration);
}

    2.2 の例:

    public static void Main(string[] args)
{
    var webHost = new WebHostBuilder()
        // ...
        .ConfigureLogging((hostingContext, logging) =>
        {
            logging.AddConfiguration(hostingContext.Configuration.GetSection("Logging"));
            logging.AddConsole();
        })
        // ...
}

詳細については、「.NET Core および ASP.NET Core でのログ記録」を参照してください

ASP.NET Core モジュール (ANCM)

Visual Studio のインストール時に ASP.NET Core モジュール (ANCM) が選択されたコンポーネントではなかった場合、または ANCM の以前のバージョンがシステムにインストールされていた場合は、最新の .NET Core ホスティング バンドル インストーラー (直接ダウンロード) をダウンロードし、インストーラーを実行します。 詳細については、ホスティング バンドルに関するページを参照してください。

その他のリソース