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

作成者: Scott AddieBy Scott Addie

この記事では、既存の ASP.NET Core 1.x プロジェクトを ASP.NET Core 2.0 に更新する手順を説明します。In this article, we walk you through updating an existing ASP.NET Core 1.x project to ASP.NET Core 2.0. アプリケーションを ASP.NET Core 2.0 に移行すると、多数の新機能を利用したり、パフォーマンスを向上させたりすることができますMigrating your application to ASP.NET Core 2.0 enables you to take advantage of many new features and performance improvements.

既存の ASP.NET Core 1.x アプリケーションは、バージョン固有のプロジェクト テンプレートには基づいていません。Existing ASP.NET Core 1.x applications are based off of version-specific project templates. ASP.NET Core のフレームワークの進化に伴い、プロジェクト テンプレートと、それに含まれるスタート コードも進化しています。As the ASP.NET Core framework evolves, so do the project templates and the starter code contained within them. ASP.NET Core のフレームワークを更新するだけでなく、アプリケーションのコードも更新する必要があります。In addition to updating the ASP.NET Core framework, you need to update the code for your application.

必須コンポーネントPrerequisites

ASP.NET Core の概要」を参照してください。See Get Started with ASP.NET Core.

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

.NET Core をターゲットとするプロジェクトでは、.NET Core 2.0 以上のバージョンの TFM を使用する必要があります。Projects targeting .NET Core should use the TFM of a version greater than or equal to .NET Core 2.0. .csproj ファイルで <TargetFramework> ノードを探し、その内側のテキストを netcoreapp2.0 に置き換えます。Search for the <TargetFramework> node in the .csproj file, and replace its inner text with netcoreapp2.0:

<TargetFramework>netcoreapp2.0</TargetFramework>

.NET Framework をターゲットとするプロジェクトでは、.NET Framework 4.6.1 以上の TFM バージョンを使用する必要があります。Projects targeting .NET Framework should use the TFM of a version greater than or equal to .NET Framework 4.6.1. .csproj ファイルで <TargetFramework> ノードを探し、その内側のテキストを net461 に置き換えます。Search for the <TargetFramework> node in the .csproj file, and replace its inner text with net461:

<TargetFramework>net461</TargetFramework>

注意

.NET Core 1.x よりセキュリティ上外部からアクセスできるところの多い .NET core 2.0.NET Core 2.0 offers a much larger surface area than .NET Core 1.x. NET Core 1.x に API がないためだけに .NET Framework をターゲットにする場合、.NET Core 2.0 をターゲットにすると機能します。If you're targeting .NET Framework solely because of missing APIs in .NET Core 1.x, targeting .NET Core 2.0 is likely to work.

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

特定の .NET Core SDK バージョンをターゲットとするよう、ソリューションが global.json ファイルに依存する場合、コンピューターにインストールされている 2.0 バージョンを使用するよう、その version プロパティを更新します。If your solution relies upon a global.json file to target a specific .NET Core SDK version, update its version property to use the 2.0 version installed on your machine:

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

パッケージ参照の更新Update package references

1.x プロジェクト内の .csproj ファイルには、プロジェクトによって使用される各 NuGet パッケージの一覧があります。The .csproj file in a 1.x project lists each NuGet package used by the project.

.NET Core 2.0 をターゲットとする ASP.NET Core 2.0 プロジェクトでは、.csproj ファイル内の 1 つのメタパッケージへの参照によってパッケージのコレクションが置き換えられます。In an ASP.NET Core 2.0 project targeting .NET Core 2.0, a single metapackage reference in the .csproj file replaces the collection of packages:

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

メタパッケージには、ASP.NET Core 2.0 および Entity Framework Core 2.0 のすべての機能が含まれます。All the features of ASP.NET Core 2.0 and Entity Framework Core 2.0 are included in the metapackage.

.NET Framework をターゲットとする ASP.NET Core 2.0 プロジェクトは、個々の NuGet パッケージを参照し続ける必要があります。ASP.NET Core 2.0 projects targeting .NET Framework should continue to reference individual NuGet packages. <PackageReference /> ノードの Version 属性を 2.0.0 に更新します。Update the Version attribute of each <PackageReference /> node to 2.0.0.

たとえば、.NET Framework をターゲットとする一般的な ASP.NET Core 2.0 プロジェクトで使用される <PackageReference /> ノードの一覧を次に示します。For example, here's the list of <PackageReference /> nodes used in a typical ASP.NET Core 2.0 project targeting .NET Framework:

<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>

.NET Core CLI ツールの更新Update .NET Core CLI tools

.csproj ファイルで、<DotNetCliToolReference /> ノードのそれぞれの Version 属性を 2.0.0 に更新します。In the .csproj file, update the Version attribute of each <DotNetCliToolReference /> node to 2.0.0.

たとえば、.NET Core 2.0 をターゲットとする一般的な ASP.NET Core 2.0 プロジェクトで使用される CLI ツールの一覧を次に示します。For example, here's the list of CLI tools used in a typical ASP.NET Core 2.0 project targeting .NET Core 2.0:

<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 プロパティの名前変更Rename Package Target Fallback property

1.x プロジェクトの .csproj ファイルでは、PackageTargetFallback ノードと変数を使用していました。The .csproj file of a 1.x project used a PackageTargetFallback node and variable:

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

ノードと変数の両方を AssetTargetFallback に名前変更します。Rename both the node and variable to AssetTargetFallback:

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

Program.cs の Main メソッドの更新Update Main method in Program.cs

1.x プロジェクトでは、Program.csMain メソッドは次のようでした。In 1.x projects, the Main method of Program.cs looked like this:

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.csMain メソッドは次のように簡素化されました。In 2.0 projects, the Main method of Program.cs has been simplified:

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 のような製品機能が必要です。The adoption of this new 2.0 pattern is highly recommended and is required for product features like Entity Framework (EF) Core Migrations to work. たとえば、パッケージ マネージャーのコンソール ウィンドウから Update-Database を実行したり、(ASP.NET Core 2.0 に変換されたプロジェクトで) コマンドラインから dotnet ef database update を実行したりすると、次のエラーが発生します。For example, running Update-Database from the Package Manager Console window or dotnet ef database update from the command line (on projects converted to ASP.NET Core 2.0) generates the following error:

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.

構成プロバイダーの追加Add configuration providers

1.x プロジェクトでは、アプリへの構成プロバイダーの追加は Startup コンストラクターを使用して実行しました。In 1.x projects, adding configuration providers to an app was accomplished via the Startup constructor. この手順には ConfigurationBuilder のインスタンスの作成、適用可能なプロバイダー (環境変数、アプリの設定など) の読み込み、IConfigurationRoot のメンバーの初期化などが伴いました。The steps involved creating an instance of ConfigurationBuilder, loading applicable providers (environment variables, app settings, etc.), and initializing a member of 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; }

前の例では、IHostingEnvironment.EnvironmentName プロパティに一致する、appsettings.json とすべての appsettings.<EnvironmentName>.json ファイルの構成設定の Configuration メンバーを読み込んでいます。The preceding example loads the Configuration member with configuration settings from appsettings.json as well as any appsettings.<EnvironmentName>.json file matching the IHostingEnvironment.EnvironmentName property. これらのファイルの場所は Startup.cs と同じパスです。The location of these files is at the same path as Startup.cs.

2.0 プロジェクトでは、1.x プロジェクトに固有の定型句による構成コードがバックグラウンドで実行されていました。In 2.0 projects, the boilerplate configuration code inherent to 1.x projects runs behind-the-scenes. たとえば、環境変数とアプリの設定は起動時に読み込まれます。For example, environment variables and app settings are loaded at startup. 同等の Startup.cs コードは、挿入されたインスタンスによって IConfiguration の初期化に削減されます。The equivalent Startup.cs code is reduced to IConfiguration initialization with the injected instance:

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

public IConfiguration Configuration { get; }

WebHostBuilder.CreateDefaultBuilder によって追加された既定のプロバイダーを削除するには、ConfigureAppConfiguration の内部の IConfigurationBuilder.Sources プロパティで Clear メソッドを呼び出します。To remove the default providers added by WebHostBuilder.CreateDefaultBuilder, invoke the Clear method on the IConfigurationBuilder.Sources property inside of ConfigureAppConfiguration. プロバイダーを戻すには、Program.csConfigureAppConfiguration メソッドを利用します。To add providers back, utilize the ConfigureAppConfiguration method in Program.cs:

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 メソッドで使用される構成は、こちらで確認できます。The configuration used by the CreateDefaultBuilder method in the preceding code snippet can be seen here.

詳細については、「ASP.NET Core の構成」を参照してください。For more information, see Configuration in ASP.NET Core.

データベース初期化コードの移動Move database initialization code

EF Core 1.x を利用する 1.x プロジェクトで、dotnet ef migrations add のようなコマンドは以下を行います。In 1.x projects using EF Core 1.x, a command such as dotnet ef migrations add does the following:

  1. Startup インスタンスをインスタンス化するInstantiates a Startup instance
  2. ConfigureServices メソッドを呼び出し、依存性の注入にすべてのサービスを登録する (DbContext タイプを含める)Invokes the ConfigureServices method to register all services with dependency injection (including DbContext types)
  3. その必要なタスクを実行するPerforms its requisite tasks

EF Core 2.0 を使用する 2.0 プロジェクトでは、Program.BuildWebHost が呼び出され、アプリケーション サービスを取得します。In 2.0 projects using EF Core 2.0, Program.BuildWebHost is invoked to obtain the application services. 1.x とは異なり、Startup.Configure を呼び出すという副作用が加わります。Unlike 1.x, this has the additional side effect of invoking Startup.Configure. 1.x アプリがその Configure メソッドでデータベース初期化コードを呼び出すと、予想外の問題が発生することがあります。If your 1.x app invoked database initialization code in its Configure method, unexpected problems can occur. たとえば、データベースがまだ存在しない場合、EF Core 移行コマンド実行前にシード処理コードが実行されます。For example, if the database doesn't yet exist, the seeding code runs before the EF Core Migrations command execution. この問題が原因で、データベースがまだ存在しない場合に dotnet ef migrations list コマンドが失敗します。This problem causes a dotnet ef migrations list command to fail if the database doesn't yet exist.

Startup.csConfigure メソッドで次の 1.x シード処理初期化コードを検討してください。Consider the following 1.x seed initialization code in the Configure method of Startup.cs:

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

SeedData.Initialize(app.ApplicationServices);

2.0 プロジェクトでは、Program.csMain メソッドに SeedData.Initialize 呼び出しを移動します。In 2.0 projects, move the SeedData.Initialize call to the Main method of Program.cs:

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 ホストのビルドと構成以外を行うことは正しくない使用例となります。As of 2.0, it's bad practice to do anything in BuildWebHost except build and configure the web host. アプリケーションの実行に関するあらゆることは BuildWebHost の外側で、一般的には Program.csMain メソッドで処理する必要があります。Anything that's about running the application should be handled outside of BuildWebHost — typically in the Main method of Program.cs.

Razor ビュー コンパイル設定の確認Review Razor view compilation setting

ユーザーに最も重要なことは、アプリケーションを高速に起動することとパブリッシュされたバンドル数を少なくすることです。Faster application startup time and smaller published bundles are of utmost importance to you. これらの理由から、ASP.NET Core 2.0 では Razor ビュー コンパイルが既定で有効になっています。For these reasons, Razor view compilation is enabled by default in ASP.NET Core 2.0.

MvcRazorCompileOnPublish プロパティを true に設定する必要がなくなりました。Setting the MvcRazorCompileOnPublish property to true is no longer required. ビューのコンパイルを無効にしている場合を除き、.csproj ファイルからこのプロパティが削除されている場合があります。Unless you're disabling view compilation, the property may be removed from the .csproj file.

.NET Framework をターゲットとする場合、継続して .csproj ファイルの Microsoft.AspNetCore.Mvc.Razor.ViewCompilation NuGet パッケージを明示的に参照する必要があります。When targeting .NET Framework, you still need to explicitly reference the Microsoft.AspNetCore.Mvc.Razor.ViewCompilation NuGet package in your .csproj file:

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

Application Insights の "Light-Up" 機能の利用Rely on Application Insights "light-up" features

アプリケーション パフォーマンスのインストルメンテーションは、楽に設定できることが重要です。Effortless setup of application performance instrumentation is important. Visual Studio 2017 のツールの新しい Application Insights "light-up" 機能が利用できるようになりました。You can now rely on the new Application Insights "light-up" features available in the Visual Studio 2017 tooling.

Visual Studio 2017 で作成された ASP.NET Core 1.1 プロジェクトには、既定で Application Insights が追加されています。ASP.NET Core 1.1 projects created in Visual Studio 2017 added Application Insights by default. Program.csStartup.cs 外で、Application Insights SDK を直接使用していない場合、次の手順に従います。If you're not using the Application Insights SDK directly, outside of Program.cs and Startup.cs, follow these steps:

  1. .NET Core をターゲットにする場合、.csproj ファイルから次の <PackageReference /> ノードを削除します。If targeting .NET Core, remove the following <PackageReference /> node from the .csproj file:

    <PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="2.0.0" />
    
  2. .NET Core をターゲットにする場合、Program.cs から UseApplicationInsights 拡張メソッド呼び出しを削除します。If targeting .NET Core, remove the UseApplicationInsights extension method invocation from Program.cs:

    public static void Main(string[] args)
    {
        var host = new WebHostBuilder()
            .UseKestrel()
            .UseContentRoot(Directory.GetCurrentDirectory())
            .UseIISIntegration()
            .UseStartup<Startup>()
            .UseApplicationInsights()
            .Build();
    
        host.Run();
    }
    
  3. _Layout.cshtml から Application Insights のクライアント側 API 呼び出しを削除します。Remove the Application Insights client-side API call from _Layout.cshtml. これによって、次の 2 つのコード行が作成されます。It comprises the following two lines of code:

    @inject Microsoft.ApplicationInsights.AspNetCore.JavaScriptSnippet JavaScriptSnippet
    @Html.Raw(JavaScriptSnippet.FullScript)
    

Application Insights SDK を直接使用している場合は、それを継続してください。If you are using the Application Insights SDK directly, continue to do so. 2.0 のメタパッケージには、Application Insights の最新バージョンが含まれているので、以前のバージョンを参照している場合、パッケージのダウングレード エラーが表示されます。The 2.0 metapackage includes the latest version of Application Insights, so a package downgrade error appears if you're referencing an older version.

認証/ID の機能強化の採用Adopt authentication/Identity improvements

ASP.NET Core 2.0 には、新しい認証モデルと ASP.NET Core ID への大幅な変更があります。ASP.NET Core 2.0 has a new authentication model and a number of significant changes to ASP.NET Core Identity. 個々のユーザー アカウントを有効にしてプロジェクトを作成した場合や認証または ID を手動で追加した場合、「Migrate Authentication and Identity to ASP.NET Core 2.0」(ASP.NET Core 2.0 への認証と ID の移行) を参照してください。If you created your project with Individual User Accounts enabled, or if you have manually added authentication or Identity, see Migrate Authentication and Identity to ASP.NET Core 2.0.

その他の技術情報Additional resources