ASP.NET Core 1.x から 2.0 への移行

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

この記事では、既存の ASP.NET Core 1.x プロジェクトを ASP.NET Core 2.0 に更新する手順を説明します。アプリケーションを ASP.NET Core 2.0 に移行すると、多数の新機能を利用したり、パフォーマンスを向上させたりすることができます。

既存の ASP.NET Core 1.x アプリケーションは、バージョン固有のプロジェクトテンプレートには基づいていません。 ASP.NET Core のフレームワークの進化に伴い、プロジェクトテンプレートと、それに含まれるスタートコードも進化しています。 ASP.NET Core のフレームワークを更新するだけでなく、アプリケーションのコードも更新する必要があります。

必須コンポーネント

「ASP.NET Core の概要」を参照してください。

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

.NET Core をターゲットとするプロジェクトでは、.NET Core 2.0 以上のバージョンの TFM を使用する必要があります。 .csproj ファイルで <TargetFramework> ノードを探し、その内側のテキストを netcoreapp2.0 に置き換えます。

<TargetFramework>netcoreapp2.0</TargetFramework>

.NET Framework をターゲットとするプロジェクトでは、.NET Framework 4.6.1 以上の TFM バージョンを使用する必要があります。 .csproj ファイルで <TargetFramework> ノードを探し、その内側のテキストを net461 に置き換えます。

<TargetFramework>net461</TargetFramework>

注意

.NET Core 1.x よりセキュリティ上外部からアクセスできるところの多い .NET core 2.0 NET Core 1.x に API がないためだけに .NET Framework をターゲットにする場合、.NET Core 2.0 をターゲットにすると機能します。

プロジェクトファイルに <RuntimeFrameworkVersion>1.{sub-version}</RuntimeFrameworkVersion> が含まれている場合は、こちらの GitHub の問題を参照してください。

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

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

{
  "sdk": {
    "version": "2.0.0"
  }
}

パッケージ参照の更新

1\.x プロジェクト内の .csproj ファイルには、プロジェクトによって使用される各 NuGet パッケージの一覧があります。

.NET Core 2.0 をターゲットとする ASP.NET Core 2.0 プロジェクトでは、 .csproj ファイル内の 1 つのメタパッケージへの参照によってパッケージのコレクションが置き換えられます。

<ItemGroup>
  <PackageReference Include="Microsoft.AspNetCore.All" Version="2.0.9" />
</ItemGroup>

メタパッケージには、ASP.NET Core 2.0 および Entity Framework Core 2.0 のすべての機能が含まれます。

.NET Framework をターゲットとする ASP.NET Core 2.0 プロジェクトは、個々の NuGet パッケージを参照し続ける必要があります。各 <PackageReference /> ノードの Version 属性を 2.0.0 に更新します。

たとえば、.NET Framework をターゲットとする一般的な ASP.NET Core 2.0 プロジェクトで使用される <PackageReference /> ノードの一覧を次に示します。

<ItemGroup>
  <PackageReference Include="Microsoft.AspNetCore" Version="2.0.0" />
  <PackageReference Include="Microsoft.AspNetCore.Authentication.Cookies" Version="2.0.0" />
  <PackageReference Include="Microsoft.AspNetCore.Diagnostics.EntityFrameworkCore" Version="2.0.0" />
  <PackageReference Include="Microsoft.AspNetCore.Identity.EntityFrameworkCore" Version="2.0.0" />
  <PackageReference Include="Microsoft.AspNetCore.Mvc" Version="2.0.0" />
  <PackageReference Include="Microsoft.AspNetCore.Mvc.Razor.ViewCompilation" Version="2.0.0" PrivateAssets="All" />
  <PackageReference Include="Microsoft.AspNetCore.StaticFiles" Version="2.0.0" />
  <PackageReference Include="Microsoft.EntityFrameworkCore.Design" Version="2.0.0" PrivateAssets="All" />
  <PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="2.0.0" />
  <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="2.0.0" PrivateAssets="All" />
  <PackageReference Include="Microsoft.VisualStudio.Web.BrowserLink" Version="2.0.0" />
  <PackageReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Design" Version="2.0.0" PrivateAssets="All" />
</ItemGroup>

Microsoft.Extensions.CommandLineUtils パッケージは廃止されました。引き続き使用できますが、サポートされません。

.NET Core CLI ツールの更新

.csproj ファイルで、<DotNetCliToolReference /> ノードのそれぞれの Version 属性を 2.0.0 に更新します。

たとえば、.NET Core 2.0 をターゲットとする一般的な ASP.NET Core 2.0 プロジェクトで使用される CLI ツールの一覧を次に示します。

<ItemGroup>
  <DotNetCliToolReference Include="Microsoft.EntityFrameworkCore.Tools.DotNet" Version="2.0.0" />
  <DotNetCliToolReference Include="Microsoft.Extensions.SecretManager.Tools" Version="2.0.0" />
  <DotNetCliToolReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Tools" Version="2.0.0" />
</ItemGroup>

Package Target Fallback プロパティの名前変更

1\.x プロジェクトの .csproj ファイルでは、PackageTargetFallback ノードと変数を使用していました。

<PackageTargetFallback>$(PackageTargetFallback);portable-net45+win8+wp8+wpa81;</PackageTargetFallback>

ノードと変数の両方を AssetTargetFallback に名前変更します。

<AssetTargetFallback>$(AssetTargetFallback);portable-net45+win8+wp8+wpa81;</AssetTargetFallback>

Program.cs の Main メソッドの更新

1\.x プロジェクトでは、Program.cs の Main メソッドは次のようでした。

using System.IO;
using Microsoft.AspNetCore.Hosting;

namespace AspNetCoreDotNetCore1App
{
    public class Program
    {
        public static void Main(string[] args)
        {
            var host = new WebHostBuilder()
                .UseKestrel()
                .UseContentRoot(Directory.GetCurrentDirectory())
                .UseIISIntegration()
                .UseStartup<Startup>()
                .UseApplicationInsights()
                .Build();

            host.Run();
        }
    }
}

2\.0 プロジェクトでは、Program.cs の Main メソッドは次のように簡素化されました。

using Microsoft.AspNetCore;
using Microsoft.AspNetCore.Hosting;

namespace AspNetCoreDotNetCore2App
{
    public class Program
    {
        public static void Main(string[] args)
        {
            BuildWebHost(args).Run();
        }

        public static IWebHost BuildWebHost(string[] args) =>
            WebHost.CreateDefaultBuilder(args)
                .UseStartup<Startup>()
                .Build();
    }
}

この新しい 2.0 のパターンの導入は強く推奨され、これらの動作には、Entity Framework (EF) Core Migrations のような製品機能が必要です。たとえば、パッケージマネージャーのコンソールウィンドウから Update-Database を実行したり、(ASP.NET Core 2.0 に変換されたプロジェクトで) コマンドラインから dotnet ef database update を実行したりすると、次のエラーが発生します。

Unable to create an object of type '<Context>'. Add an implementation of 'IDesignTimeDbContextFactory<Context>' to the project, or see https://go.microsoft.com/fwlink/?linkid=851728 for additional patterns supported at design time.

構成プロバイダーの追加

1\.x プロジェクトでは、アプリへの構成プロバイダーの追加は Startup コンストラクターを使用して実行しました。この手順には ConfigurationBuilder のインスタンスの作成、適用可能なプロバイダー (環境変数、アプリの設定など) の読み込み、IConfigurationRoot のメンバーの初期化などが伴いました。

public Startup(IHostingEnvironment env)
{
    var builder = new ConfigurationBuilder()
        .SetBasePath(env.ContentRootPath)
        .AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)
        .AddJsonFile($"appsettings.{env.EnvironmentName}.json", optional: true);

    if (env.IsDevelopment())
    {
        builder.AddUserSecrets<Startup>();
    }

    builder.AddEnvironmentVariables();
    Configuration = builder.Build();
}

public IConfigurationRoot Configuration { get; }

前の例では、appsettings.json と、IHostingEnvironment.EnvironmentName プロパティに一致する appsettings.{Environment}.json ファイルとから、構成設定を含む Configuration メンバーを読み込んでいます。これらのファイルの場所は Startup.cs と同じパスです。

2\.0 プロジェクトでは、1.x プロジェクトに固有の定型句による構成コードがバックグラウンドで実行されていました。たとえば、環境変数とアプリの設定は起動時に読み込まれます。同等の Startup.cs コードは、挿入されたインスタンスによって IConfiguration の初期化に削減されます。

public Startup(IConfiguration configuration)
{
    Configuration = configuration;
}

public IConfiguration Configuration { get; }

WebHostBuilder.CreateDefaultBuilder によって追加された既定のプロバイダーを削除するには、ConfigureAppConfiguration の内部の IConfigurationBuilder.Sources プロパティで Clear メソッドを呼び出します。プロバイダーを戻すには、Program.cs の ConfigureAppConfiguration メソッドを利用します。

public static void Main(string[] args)
{
    BuildWebHost(args).Run();
}

public static IWebHost BuildWebHost(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureAppConfiguration((hostContext, config) =>
        {
            // delete all default configuration providers
            config.Sources.Clear();
            config.AddJsonFile("myconfig.json", optional: true);
        })
        .Build();

前のコードスニペットの CreateDefaultBuilder メソッドで使用される構成は、こちらで確認できます。

詳細については、「ASP.NET Core の構成」を参照してください。

データベース初期化コードの移動

EF Core 1.x を利用する 1.x プロジェクトで、dotnet ef migrations add のようなコマンドは以下を行います。

Startup インスタンスをインスタンス化する
ConfigureServices メソッドを呼び出し、依存性の注入にすべてのサービスを登録する (DbContext タイプを含める)
その必要なタスクを実行する

EF Core 2.0 を使用する 2.0 プロジェクトでは、アプリケーションサービスを取得するために Program.BuildWebHost が呼び出されます。 1\.x とは異なり、Startup.Configure を呼び出すという副作用が加わります。 1\.x アプリがその Configure メソッドでデータベース初期化コードを呼び出すと、予想外の問題が発生することがあります。たとえば、データベースがまだ存在しない場合、EF Core 移行コマンド実行前にシード処理コードが実行されます。この問題が原因で、データベースがまだ存在しない場合に dotnet ef migrations list コマンドが失敗します。

Startup.cs の Configure メソッドで次の 1.x シード処理初期化コードを検討してください。

app.UseMvc(routes =>
{
    routes.MapRoute(
        name: "default",
        template: "{controller=Home}/{action=Index}/{id?}");
});

SeedData.Initialize(app.ApplicationServices);

2\.0 プロジェクトでは、Program.cs の Main メソッドに SeedData.Initialize 呼び出しを移動します。

var host = BuildWebHost(args);

using (var scope = host.Services.CreateScope())
{
    var services = scope.ServiceProvider;

    try
    {
        // Requires using RazorPagesMovie.Models;
        SeedData.Initialize(services);
    }
    catch (Exception ex)
    {
        var logger = services.GetRequiredService<ILogger<Program>>();
        logger.LogError(ex, "An error occurred seeding the DB.");
    }
}

host.Run();

2\.0 以降、BuildWebHost で Web ホストのビルドと構成以外を行うことは正しくない使用例となります。アプリケーションの実行に関するあらゆることは BuildWebHost の外側で、一般的には Program.cs の Main メソッドで処理する必要があります。

Razor ビューコンパイル設定の確認

ユーザーに最も重要なことは、アプリケーションを高速に起動することとパブリッシュされたバンドル数を少なくすることです。これらの理由から、ASP.NET Core 2.0 では Razor ビューコンパイルが既定で有効になっています。

MvcRazorCompileOnPublish プロパティを true に設定する必要がなくなりました。ビューのコンパイルを無効にしている場合を除き、 .csproj ファイルからこのプロパティが削除されている場合があります。

.NET Framework をターゲットとする場合は、継続して .csproj ファイルの Microsoft.AspNetCore.Mvc.Razor.ViewCompilation NuGet パッケージを明示的に参照する必要があります。

<PackageReference Include="Microsoft.AspNetCore.Mvc.Razor.ViewCompilation" Version="2.0.0" PrivateAssets="All" />

Application Insights の "Light-Up" 機能の利用

アプリケーションパフォーマンスのインストルメンテーションは、楽に設定できることが重要です。 Visual Studio 2017 のツールの新しい Application Insights "light-up" 機能が利用できるようになりました。

Visual Studio 2017 で作成された ASP.NET Core 1.1 プロジェクトには、既定で Application Insights が追加されています。 Program.cs と Startup.cs 外で、Application Insights SDK を直接使用していない場合、次の手順に従います。

.NET Core をターゲットにする場合、 .csproj ファイルから次の <PackageReference /> ノードを削除します。
```
<PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="2.0.0" />
```

.NET Core をターゲットにする場合、Program.cs から UseApplicationInsights 拡張メソッド呼び出しを削除します。

public static void Main(string[] args)
{
    var host = new WebHostBuilder()
        .UseKestrel()
        .UseContentRoot(Directory.GetCurrentDirectory())
        .UseIISIntegration()
        .UseStartup<Startup>()
        .UseApplicationInsights()
        .Build();

    host.Run();
}

_Layout.cshtml から Application Insights のクライアント側 API 呼び出しを削除します。これによって、次の 2 つのコード行が作成されます。
```
@inject Microsoft.ApplicationInsights.AspNetCore.JavaScriptSnippet JavaScriptSnippet
@Html.Raw(JavaScriptSnippet.FullScript)
```

Application Insights SDK を直接使用している場合は、それを継続してください。 2\.0 のメタパッケージには、Application Insights の最新バージョンが含まれているので、以前のバージョンを参照している場合、パッケージのダウングレードエラーが表示されます。

認証、Identity の機能強化の採用

ASP.NET Core 2.0 には、新しい認証モデルと ASP.NET Core Identity への大幅な変更があります。個々のユーザーアカウントを有効にしてプロジェクトを作成した場合や認証または Identity を手動で追加した場合、「IdentityASP.NET Core 2.0 への認証との移行」を参照してください。

その他の技術情報

ASP.NET Core 2.0 での互換性に影響する変更点

ASP.NET Core 1.x から 2.0 への移行

必須コンポーネント

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

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

パッケージ参照の更新

.NET Core CLI ツールの更新

Package Target Fallback プロパティの名前変更

Program.cs の Main メソッドの更新

構成プロバイダーの追加

データベース初期化コードの移動

Razor ビューコンパイル設定の確認

Application Insights の "Light-Up" 機能の利用

認証、Identity の機能強化の採用

その他の技術情報

フィードバック

その他のリソース

ASP.NET Core 1.x から 2.0 への移行

必須コンポーネント

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

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

パッケージ参照の更新

.NET Core CLI ツールの更新

Package Target Fallback プロパティの名前変更

Program.cs の Main メソッドの更新

構成プロバイダーの追加

データベース初期化コードの移動

Razor ビュー コンパイル設定の確認

Application Insights の "Light-Up" 機能の利用

認証、Identity の機能強化の採用

その他の技術情報

フィードバック

その他のリソース

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

Razor ビューコンパイル設定の確認