ASP.NET Core 1.x에서 2.0으로 마이그레이션

2025-06-21

이 문서에서는 기존 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 을 사용해야 합니다. 파일에서 <TargetFramework> 노드를 검색하고 내부 텍스트를 .csproj로 바꿉니다.

<TargetFramework>netcoreapp2.0</TargetFramework>

.NET Framework를 대상으로 하는 프로젝트는 .NET Framework 4.6.1보다 크거나 같은 버전의 TFM을 사용해야 합니다. 파일에서 <TargetFramework> 노드를 검색하고 내부 텍스트를 .csproj로 바꿉니다.

<TargetFramework>net461</TargetFramework>

비고

.NET Core 2.0은 .NET Core 1.x보다 훨씬 더 큰 노출 영역을 제공합니다. .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 버전을 대상으로 하는 파일에 의존하는 경우 컴퓨터에 설치된 2.0 버전을 사용하도록 해당 version 속성을 업데이트합니다.

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

패키지 참조 업데이트

1.x 프로젝트의 파일에는 .csproj 프로젝트에서 사용하는 각 NuGet 패키지가 나열됩니다.

.NET Core 2.0을 대상으로 하는 ASP.NET Core 2.0 프로젝트에서 파일의 단일 메타패키지 참조 .csproj 는 패키지 컬렉션을 대체합니다.

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

ASP.NET Core 2.0 및 Entity Framework Core 2.0의 모든 기능이 메타패키지에 포함됩니다.

ASP.NET .NET Framework를 대상으로 하는 Core 2.0 프로젝트는 개별 NuGet 패키지를 계속 참조해야 합니다. 각 Version 노드의 <PackageReference /> 특성을 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 CLI 도구 업데이트

.csproj 파일에서 각 Version 노드의 <DotNetCliToolReference /> 속성을 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>

패키지 대상 대체 속성의 이름 변경

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 프로젝트에서 Main 메서드의 Program.cs는 다음과 같았습니다.

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 프로젝트에서는 Main의 Program.cs 메서드가 간소화되었습니다.

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 패턴을 채택하는 것이 좋으며 EF(Entity Framework) 핵심 마이그레이션 과 같은 제품 기능이 작동하려면 필요합니다. 예를 들어 패키지 관리자 콘솔 창 또는 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; }

앞의 Configuration 예제에서는 appsettings.json에서 구성 설정과 appsettings.{Environment}.json 속성에 일치하는 IHostingEnvironment.EnvironmentName 파일로 멤버를 로드합니다. 이러한 파일의 위치는 .와 동일한 경로 Startup.cs에 있습니다.

2.0 프로젝트에서는 1.x 프로젝트에 내재된 상용구 구성 코드가 백그라운드에서 실행됩니다. 예를 들어 시작 시 환경 변수 및 앱 설정이 로드됩니다. 해당하는 Startup.cs 코드는 삽입된 인스턴스를 사용하여 IConfiguration 초기화로 단순화됩니다.

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

public IConfiguration Configuration { get; }

기본 공급자를 제거하려면 WebHostBuilder.CreateDefaultBuilder 안의 Clear 속성에서 IConfigurationBuilder.Sources 메서드를 호출하십시오. 공급자를 다시 추가하려면 다음에서 메서드를 ConfigureAppConfiguration 활용합니다.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 구성은 여기에서 확인할 수 있습니다.

자세한 내용은 ASP.NET Core의 구성을 참조하세요.

데이터베이스 초기화 코드 이동

1.x를 사용하는 EF Core 1.x 프로젝트에서는 다음과 같은 dotnet ef migrations add 명령을 사용합니다.

Startup 인스턴스를 생성합니다
ConfigureServices 종속성 주입(형식 포함DbContext)을 사용하여 모든 서비스를 등록하는 메서드를 호출합니다.
필수 작업을 수행합니다.

애플리케이션 서비스를 가져오기 위해 EF Core이 호출되는 2.0 프로젝트에서 Program.BuildWebHost 2.0을 사용합니다. 1.x와 달리, 추가적인 효과로 Startup.Configure를 호출합니다. 1.x 앱이 해당 Configure 메서드에서 데이터베이스 초기화 코드를 호출한 경우 예기치 않은 문제가 발생할 수 있습니다. 예를 들어 데이터베이스가 아직 없는 경우 마이그레이션 명령 실행 전에 시드 코드가 EF Core 실행됩니다. 이 문제로 인해 데이터베이스가 dotnet ef migrations list 아직 없는 경우 명령이 실패합니다.

Configure의 Startup.cs 메서드에서 다음 1.x 시드 초기화 코드를 고려하십시오.

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

SeedData.Initialize(app.ApplicationServices);

2.0 프로젝트에서는 SeedData.Initialize 호출을 Main의 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 아무 것도 수행하는 것이 좋지 않습니다. 애플리케이션 실행에 관련된 모든 것은 일반적으로 BuildWebHost의 Main 메서드에서 처리되며, Program.cs 외부에서 이루어져야 합니다.

뷰 컴파일 설정 검토 Razor

애플리케이션 시작 시간이 빨라지고 게시된 번들이 매우 중요합니다. 이러한 이유로 Razor 보기 컴파일 은 기본적으로 ASP.NET Core 2.0에서 사용하도록 설정됩니다.

MvcRazorCompileOnPublish 속성을 true로 설정하는 것은 더 이상 필요하지 않습니다. 뷰 컴파일을 사용하지 않도록 설정하지 않으면 파일에서 .csproj 속성이 제거될 수 있습니다.

.NET Framework를 대상으로 하는 경우에도 Razor 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" 기능을 사용할 수 있습니다.

ASP.NET Visual Studio 2017에서 만든 Core 1.1 프로젝트는 기본적으로 Application Insights를 추가했습니다. Application Insights SDK를 Program.cs 및 Startup.cs를 직접 사용하지 않는 경우, 다음 단계를 수행합니다.

.NET Core를 대상으로 하는 경우 파일에서 다음 <PackageReference /> 노드를 제거합니다 .csproj .
```
<PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="2.0.0" />
```

.NET Core를 대상으로 하는 경우 UseApplicationInsights에서 Program.cs 확장 메서드 호출을 제거합니다.

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 호출을 제거합니다. 이 코드는 다음 두 줄의 코드로 구성됩니다.
```
@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을 참조하세요.

추가 리소스

ASP.NET Core 2.0의 주요 변경 내용

다음을 통해 공유

ASP.NET Core 1.x에서 2.0으로 마이그레이션

필수 조건

TFM(대상 프레임워크 모니커) 업데이트

global.json에서 .NET Core SDK 버전 업데이트

패키지 참조 업데이트

.NET CLI 도구 업데이트

패키지 대상 대체 속성의 이름 변경

Program.cs Main 메서드 업데이트

구성 공급자 추가

데이터베이스 초기화 코드 이동

뷰 컴파일 설정 검토 Razor

Application Insights "light-up" 기능 사용

인증 채택/Identity 개선 사항

추가 리소스

피드백

추가 리소스