ASP.NET Core 2.1에서 2.2로 마이그레이션하기

  • 아티클

작성자: Scott Addie

이 문서에서는 기존의 ASP.NET Core 2.1 프로젝트를 ASP.NET Core 2.2로 변경하는 방법을 설명합니다.

필수 조건

Warning

Visual Studio 2017을 사용하는 경우 Visual Studio에서 작동하지 않는 .NET Core SDK 버전에 대한 자세한 내용은 dotnet/sdk issue #3124(dotnet/sdk 문제 #3124)를 참조하세요.

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

.NET Core를 대상으로 하는 프로젝트는 .NET Core 2.2 이상의 TFM을 사용해야 합니다. 프로젝트 파일에서 <TargetFramework> 노드의 내부 텍스트를 netcoreapp2.2로 업데이트합니다.

<TargetFramework>netcoreapp2.2</TargetFramework>

.NET Framework를 대상으로 하는 프로젝트는 .NET Framework 4.6.1 버전 이상의 TFM을 계속 사용할 수 있습니다.

<TargetFramework>net461</TargetFramework>

IIS In-Process 호스팅 모델 채택

IIS의 In-Process 호스팅 모델을 채택하려면 값을 InProcess로 지정한 <AspNetCoreHostingModel> 속성을 프로젝트 파일의 <PropertyGroup>에 추가합니다.

<AspNetCoreHostingModel>InProcess</AspNetCoreHostingModel>

In-Process 호스팅 모델은 .NET Framework를 대상으로 하는 ASP.NET Core 앱을 지원하지 않습니다.

자세한 내용은 IIS용 ANCM(ASP.NET Core 모듈)을 참조하세요.

사용자 지정 web.config 파일 업데이트

프로젝트 루트의 사용자 지정 web.config 파일을 사용하여 게시된 web.config 파일을 생성하는 프로젝트의 경우:

  • ASP.NET Core Module(name="aspNetCore")을 추가하는 <handlers> 항목에서 modules 특성 값을 AspNetCoreModule에서 AspNetCoreModuleV2로 변경합니다.
  • <aspNetCore> 요소에서 호스팅 모델 특성(hostingModel="InProcess")을 추가합니다.

web.config 파일에 대한 자세한 내용과 예제는 IIS용 ANCM(ASP.NET Core 모듈)을 참조하세요.

패키지 참조 업데이트

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

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

솔루션이 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을 호출하는 경우에는 ConfigureKestrel을 호출하여 IIS In-Process 호스팅 모델의 충돌을 방지하기 위해 UseKestrel 대신 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 하세요.

호환성 버전 수정하기

Startup.ConfigureServices에서 호환성 버전을 Version_2_2로 업데이트합니다.

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

CORS 정책 업데이트

ASP.NET Core 2.2에서 CORS 미들웨어는 정책이 모든 원본을 허용하고 자격 증명을 허용하는 경우 와일드카드 원본(*)으로 응답합니다. 와일드카드 원본(*)을 지정하면 자격 증명이 지원되지 않으므로 브라우저에서 CORS 요청을 허용하지 않습니다. 클라이언트의 문제를 해결하는 옵션을 비롯한 자세한 내용은 MDN 웹 문서를 참조하세요.

서버에서 이 문제를 해결하려면 다음 작업 중 하나를 수행합니다.

  • 더 이상 자격 증명을 허용하지 않도록 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 In-Process 호스팅을 사용할 때 Visual Studio에서 수동으로 빌드

브라우저 요청 환경에서 Visual Studio의 자동 빌드는 IIS In-Process 호스팅 모델에서 작동하지 않습니다. In-Process 호스팅을 사용할 때 프로젝트를 수동으로 다시 빌드해야 합니다. 이 환경에 대한 향상된 기능은 이후 버전의 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를 설치할 때 ANCM(ASP.NET Core 모듈)이 선택된 구성 요소가 아니거나 이전 버전의 ANCM이 시스템에 설치된 경우, 최신 .NET Core 호스팅 번들 설치 관리자(직접 다운로드)를 다운로드하고 설치 관리자를 실행합니다. 자세한 내용은 호스팅 번들을 참조하세요.

추가 리소스